# Hawcx backend SDKs now include a Profile Service client

> The Node, Python and Java SDKs now call the Hawcx profile service through a typed client: manage any user's profile, consents and activity from your backend, or let a signed-in user manage their own. Node 6.2.0, Python 2.2.0 and Java 0.7.0 are out.

Markdown version of <https://www.hawcx.com/blog/hawcx-sdks-profile-service-client>. Published 2026-11-09. Product updates.

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

| Change | Type | Who it affects |
| --- | --- | --- |
| `ProfileClient`: manage any user's profile, consents and activity | New | Developers |
| `UserProfileClient`: a signed-in user manages their own profile | New | Developers |
| Tokens cached and refreshed for you | New | Developers |
| Safe retries and structured errors | New | Developers |
| `/userinfo` returns profile claims for the `profile` and `address` scopes | Improved | Developers |
| `customDomain`, `buildAuthorizeUrl` and `buildEndSessionUrl` | New | Developers |
| Token exchange no longer follows redirects | Security | Developers |
| Profile Service reference docs for each SDK | New | Developers |

## 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](https://docs.hawcx.com/docs/v1/sdk-reference/backend/nodejs/profile-service), [Python](https://docs.hawcx.com/docs/v1/sdk-reference/backend/python/profile-service) and [Java](https://docs.hawcx.com/docs/v1/sdk-reference/backend/java/profile-service).

### 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](https://www.hawcx.com/blog/hawcx-sign-in-on-your-own-domain) 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](https://www.hawcx.com/passwordless) are on [docs.hawcx.com](https://docs.hawcx.com), and our earlier posts cover the [iOS SDK](https://www.hawcx.com/blog/hawcx-sdk-ios) and the [Android SDK](https://www.hawcx.com/blog/android-sdk).

## Versions in this release

| SDK | Package | Version | Registry |
| --- | --- | --- | --- |
| Node | `@hawcx/oauth-client` | 6.2.0 | [npm](https://www.npmjs.com/package/@hawcx/oauth-client) |
| Python | `hawcx-oauth-client` | 2.2.0 | [PyPI](https://pypi.org/project/hawcx-oauth-client/) |
| Java | `com.hawcx:hawcx-java-sdk` | 0.7.0 | [Maven Central](https://repo1.maven.org/maven2/com/hawcx/hawcx-java-sdk/) |

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`.
