Skip to content
IntelliAuth

Audience

The audience is a logical identifier of the API the access token is destined for. It travels on the token as the aud claim. The API receiving the token checks the claim matches its own identity; if not, it refuses.

Usually a tenant has one audience that covers everything (https://api.cymmetri.com). Some larger tenants carve out multiple audiences (https://api-payments.cymmetri.com, https://api-reporting.cymmetri.com) so a token issued for one API can't be replayed at another.

What it looks like on the token

Section titled “What it looks like on the token”

Decoded access token, partial:

{
  "iss": "https://banking-cymmetri.intelliauth.local",
  "sub": "usr_01HZ...",
  "aud": "https://api.cymmetri.com",
  "scope": "openid profile email users:read",
  "exp": 1715900400
}

The aud value matches what the application is registered with.

Where to set it

Section titled “Where to set it”

Application detail → Settings tab → General → Audience. Single string.

Convention: a URL of the API. Not necessarily a reachable URL — it's just a stable identifier. https://api.cymmetri.com works whether or not that DNS resolves.

Why it matters

Section titled “Why it matters”

Two reasons:

  1. Defence in depth. If application A's token leaks, it's only useful against API A. The same token can't be replayed against API B (different audience).
  2. Multi-API tenants. When you have separate APIs for distinct concerns, distinct audiences mean separate token blast radii. Compromise one, isolate the rest.

What your code does with it

Section titled “What your code does with it”

On the API receiving the token, validate aud matches the API's own identity. With the @intelliauth/node-sdk Express middleware this is configured at startup:

app.use(intelliAuth({
  tenantUrl: process.env.INTELLIAUTH_TENANT_URL!,
  audience:  'https://api.cymmetri.com',
}))

A token whose aud is something else gets rejected with 401. If you're using a different JWT library, the validation is one line — check the lib's docs for "audience".

When to use multiple audiences

Section titled “When to use multiple audiences”

You'd carve out multiple audiences when:

  • Your tenant serves several distinct APIs and you want strong isolation between their tokens.
  • Compliance frameworks (PCI, HIPAA) require explicit isolation between the audit / payments / data-export APIs.
  • Some applications should be able to call API A but not API B.

The mechanism for "A but not B" then is: register application A with audience: api-a, register application B with audience: api-b. They request and receive tokens only for their own audience.

What an application's audience setting actually does

Section titled “What an application's audience setting actually does”

Setting an audience on an application makes the platform issue tokens with that aud claim. The application itself doesn't have to USE the audience for its own auth — the audience is what its token is FOR (a downstream API), not what it is.

When the SPA application's frontend code calls getAccessToken(), the SDK passes the configured audience to the token request, and the resulting token's aud matches.

Multiple audiences per application

Section titled “Multiple audiences per application”

You can configure an application to be able to request tokens for multiple audiences. Useful when your SPA calls several APIs.

In the Settings tab's General section, the Audience field accepts a list (one per line in the JSON view). The SDK then specifies which audience to request when fetching a token:

const token = await getAccessToken({ audience: 'https://api.cymmetri.com' })

The platform issues a token with that specific aud. Different audience = different getAccessToken call = different token.

Token exchange across audiences

Section titled “Token exchange across audiences”

If service A holds a token for aud: api-a and needs to call API B, it can request a token exchange — see Token exchange on the developer side. The platform issues a new token with aud: api-b (if the policy permits).

This pattern keeps the original token narrow while supporting cross-API calls.

Common confusion

Section titled “Common confusion”
  • "Audience" is not "tenant". A tenant can host many audiences. An audience is an API; a tenant is the IntelliAuth slice your applications live under.
  • "Audience" is not "scope". Scope describes what the token CAN do; audience describes which API the token is FOR. A token can have scope: users:read and aud: api-a simultaneously — they're orthogonal.
  • "Audience" is not "client_id". The client_id identifies the application; the audience identifies the API. The application can request tokens for many audiences (above); the client_id is fixed.