Hawcx backend SDKs now include a Profile Service client

Published
Reading time
4 min

These Hawcx release notes cover November 9: the Node, Python and Java SDKs now call the Hawcx profile service through a typed client, so your backend no longer builds token requests and HTTP calls by hand. Node 6.2.0, Python 2.2.0 and Java 0.7.0 are out, and /userinfo returns profile claims.

The same versions are the first to carry the custom-domain helpers from the October release.

At a glance

ChangeTypeWho it affects
ProfileClient: manage any user's profile, consents and activityNewDevelopers
UserProfileClient: a signed-in user manages their own profileNewDevelopers
Tokens cached and refreshed for youNewDevelopers
Safe retries and structured errorsNewDevelopers
/userinfo returns profile claims for the profile and address scopesImprovedDevelopers
customDomain, buildAuthorizeUrl and buildEndSessionUrlNewDevelopers
Token exchange no longer follows redirectsSecurityDevelopers
Profile Service reference docs for each SDKNewDevelopers

For developers: the Profile Service client

Manage profiles from your backend

New. ProfileClient gives your backend typed methods for users, consents and the activity trail:

  • users: getUser, listUsers and iterUsers, createUser, updateUser, replaceUser, deleteUser;
  • consents: getConsents, setConsent;
  • activity: getAudit and iterAudit.

It signs in as your backend with client_credentials and private_key_jwt, so it can work on any user's profile. Python also has an AsyncProfileClient.

Let a signed-in user manage their own profile

New. forUser(idToken) returns a UserProfileClient for the signed-in user's own data: getMe, updateMe, getMyConsents, setMyConsent and getMyAudit. It exchanges the user's ID token for a token that can only reach that user's profile.

updateMe accepts only the fields a user may change, and the client refuses any other field before it sends a request. Use forUser right after sign-in, with the ID token you just received. For later work on a user's profile, use the backend methods with their user ID.

Tokens, retries and errors handled for you

New.

  • Tokens. The client gets an access token, caches it and refreshes it before it expires. If a refresh fails while the current token is still valid, it keeps using that token, so your profile calls carry on through a brief token-endpoint delay.
  • Retries. Reads and other repeatable calls retry on temporary failures and honour Retry-After. Creates and partial updates are never retried once the request was sent. A retried delete that comes back 404 counts as success when an earlier attempt may already have deleted the user.
  • Errors. Failures arrive as a ProfileApiError (Java: ProfileApiException) built from standard problem details: status, title, detail, request ID, Retry-After and the fields involved. The body of a successful response is never kept in an error, because it may hold personal data.

All three SDKs follow the same rules, so they behave the same way. Each one has a reference page: Node, Python and Java.

Profile claims from /userinfo

Improved. /userinfo now returns the signed-in user's profile claims for the profile and address scopes. Before, it returned only the subject and the email or phone number. If profile data is ever unavailable, /userinfo still answers with the base claims. This is live now, with nothing to change on your side.

For developers: custom domains and token exchange

Custom domain helpers

New. These versions add an optional customDomain to the client and two helpers, buildAuthorizeUrl and buildEndSessionUrl, that build sign-in and logout links on your own verified domain. Token exchange, key retrieval and the issuer check stay on the Hawcx issuer. Custom domains themselves went live in October.

Token exchange no longer follows redirects

Security. Exchanging an authorization code now refuses to follow a redirect from the token endpoint:

  • Node: exchangeCode throws TokenExchangeError on a redirect, or on a successful response that isn't a JSON object. A network failure sets the new network flag and carries the original error as its cause.
  • Python: the synchronous exchange_code no longer follows redirects. A token response that starts with a UTF-8 byte-order mark is accepted.
  • Java: responses are read status first, so an error response whose body is cut off keeps its HTTP status. Token and key requests are time-limited end to end.

Upgrade notes

Existing OAuth integrations need no code change. Check two things before you upgrade:

  • If you call exchangeCode behind a proxy that redirects the token endpoint, point your configuration at the final URL, because redirects now fail.
  • In Node, code that catches a raw SyntaxError or TypeError from a malformed token response should catch TokenExchangeError instead.

Setup guides for Hawcx passwordless authentication are on docs.hawcx.com, and our earlier posts cover the iOS SDK and the Android SDK.

Versions in this release

SDKPackageVersionRegistry
Node@hawcx/oauth-client6.2.0npm
Pythonhawcx-oauth-client2.2.0PyPI
Javacom.hawcx:hawcx-java-sdk0.7.0Maven Central

The /userinfo change is already live for every tenant.

Frequently asked questions

Do I need to change my existing integration?

No. Existing OAuth integrations keep working. Upgrade to use the Profile Service client or custom domains, and check the token-exchange notes above first.

What is the difference between ProfileClient and UserProfileClient?

ProfileClient acts as your backend and can work on any user's profile. UserProfileClient, from forUser(idToken), acts for one signed-in user and can reach only that user's own profile, consents and activity.

When should I use forUser?

Right after sign-in, with the ID token you just received, because the token it exchanges for lasts only as long as that ID token. For later work on a user's profile, use ProfileClient with their user ID.

Which versions add custom-domain support?

Node 6.2.0, Python 2.2.0 and Java 0.7.0. They are the first published versions with customDomain, buildAuthorizeUrl and buildEndSessionUrl.

ShareLinkedInX

Authentication for people and the AI agents they put to work.