Getting Started
How to become a consumer of the LiSTNR Token Provider and get your integration set up.
Overview
The LiSTNR Token Provider issues short-lived RS256 JWTs for authenticated clients. Tokens are signed by a private key held by the service; consumers verify them independently using the public JWKS endpoint — no call back to the token provider is needed per request.
Before you can request tokens, the LiSTNR platform team must onboard your integration. This involves registering your client_id, choosing an authentication method, defining the scopes your integration requires, and assigning you a unique audience value.
Integration patterns
There are two ways to authenticate when requesting a token. The right choice depends on your use case.
Authenticated User - Bearer Token
Your application obtains a user credentials ID token and presents it to the token provider. The token provider verifies the token, extracts the identity, and issues a LiSTNR JWT.
Use this pattern when:
- Your application has end-users who are authenticated
- You need user-identity claims in the token (email, display name, etc.)
Client Credentials / Basic Auth (server-to-server)
Your server authenticates using a client_id and client_secret provisioned during onboarding. The token provider verifies the credentials and issues a JWT for a subject you supply.
Use this pattern when:
- Your integration is a backend service with no end-user browser session
- You are calling on behalf of a known user identified by a stable identifier (e.g. an email hash)
Onboarding process
Contact the LiSTNR platform team to start the onboarding process. You will need to provide the following information:
| Item | Description |
|---|---|
| Integration name | A short, stable identifier for your system (e.g. my-service). This becomes your client_id. |
| Authentication method | Authenticated User Bearer - (see above). |
| Required scopes | The scopes your integration needs (e.g. read:profile, write:preferences). |
| Subject format | For Client Credentials: how you will identify the user in the subject field of your token request. |
| Audience identifier | A unique value identifying your service that will appear in the aud claim. Currently this will always be the same as the client id integration name. |
| Environments | Whether you need access to dev, production, or both. |
The platform team will provision:
| Item | Authenticated User Bearer | Client Credentials |
|---|---|---|
client_id | ✓ | ✓ |
client_secret | — | ✓ |
| Allowed scopes | ✓ | ✓ |
| Allowed profile claims | ✓ | — |
aud value | ✓ | ✓ |
Environments
| Environment | Base URL |
|---|---|
| Dev | https://australia-southeast1-pcone-xl-fb-dev.cloudfunctions.net/listnr-token-provider |
| Production | https://australia-southeast1-pcone-xl-fb-prod.cloudfunctions.net/listnr-token-provider |
All endpoints are under /v1/listnr-token-provider/. Dev is available for integration testing once your client is registered; production access is enabled separately.
Next steps
Once the platform team confirms your client is registered:
- Issue a token — make your first token request using your assigned credentials
- Verify a token — set up verification in your service using the public JWKS endpoint