Issuing a Token

How to request a LiSTNR JWT from the token provider.

Endpoint

POST /v1/listnr-token-provider/issue-token
Content-Type: application/json

Environment	URL
Dev	`https://australia-southeast1-pcone-xl-fb-dev.cloudfunctions.net/listnr-token-provider/v1/listnr-token-provider/issue-token`
Production	`https://australia-southeast1-pcone-xl-fb-prod.cloudfunctions.net/listnr-token-provider/v1/listnr-token-provider/issue-token`

Authentication

How you authenticate depends on the integration pattern you were onboarded with.

Authenticated User Bearer

Include the signed-in user's ID token as a Bearer credential. The subject of the issued token is taken from the verified token — you do not supply it.

POST /v1/listnr-token-provider/issue-token
Authorization: Bearer <token>
Content-Type: application/json

{
  "client_id": "<your-client-id>",
  "scope": "<your-scope>"
}

Client Credentials (Basic Auth)

Encode your client_id and client_secret as HTTP Basic credentials. Supply the subject field in the request body — this is the stable identifier for the user or entity the token represents.

POST /v1/listnr-token-provider/issue-token
Authorization: Basic <base64(client_id:client_secret)>
Content-Type: application/json

{
  "client_id": "<your-client-id>",
  "subject": "<subject-identifier>",
  "scope": "<your-scope>"
}

The client_id in the request body must match the one encoded in the Authorization header.

Request body

Field	Required	Description
`client_id`	yes	Your assigned client identifier.
`scope`	no	Space-separated list of scopes to request. Must be a subset of the scopes assigned to your client during onboarding. Omit to receive a plain identity token with no scope claims.
`subject`	Client Credentials only	A stable identifier for the user or entity the token represents. Not used for authenticated user bearer tokens — the subject is extracted from the token.

Response

200 OK

{
  "access_token": "<signed-jwt>",
  "token_type": "Bearer",
  "expires_in": 900
}

Field	Description
`access_token`	The signed JWT. Pass this as `Authorization: Bearer <access_token>` on requests to services that accept LiSTNR tokens.
`token_type`	Always `"Bearer"`.
`expires_in`	Seconds until the token expires. Tokens are valid for 15 minutes (900 seconds).

Store the token in memory. Re-request a fresh token before expiry — there is no refresh mechanism. Proactively re-issue approximately 2 minutes before the token expires.

Error responses

Errors follow the OAuth 2.0 error shape:

{
  "error": "<error-code>",
  "error_description": "<human-readable description>"
}

HTTP status	`error`	Common cause
`400`	`invalid_request`	Malformed request body or missing required field
`400`	`invalid_scope`	Requested scope is not permitted for your client
`401`	`invalid_client`	Invalid or expired credentials (authenticated user token or client secret)
`403`	`unauthorized_client`	Client exists but is disabled

Token lifetime

Property	Value
Lifetime	15 minutes
Refresh	Not supported — re-call the issue endpoint with fresh credentials
Authenticated user token lifetime	1 hour