Issue a status list entry

You can use the /issue endpoint to request a status list slot for a credential you want to issue. This endpoint lets you retrieve a new uri/idx pair from a status list, which represents a unique credential being issued to a user’s wallet.

To use the /issue endpoint you must register as a credential issuer with the Status List service, and you must send your request as a signed JSON Web Token (JWT).

When you request a new uri/idx pair for a credential on a status list, the Status List service validates your request. If this validation is successful, the Status List service will issue a new uri/idx pair on one of its status lists.

The Status List service will also return a uri and an index to where you can retrieve this credential’s status. You must include this response in your issued credential.

For guidance on how to include the Status List Service’s response in your credentials, see:

the Token status list specification for mdoc credentials
the BitString status list specification for JWT-VC credentials

Technical details

The requests to and responses from the Status List Service are the same, regardless of the credential or status list type.

Endpoint URI

The URI path for the issue endpoint is /issue.

When you register as a credential issuer with the Status List service, you get access to the internal API. You must sign the request with your private key and share public keys on your /.well-known/jwks.json endpoint. This is used to verify the JWT.

Request format

The issue endpoint only accepts HTTP POST requests.

The request must include:

header: you must provide the Content-Type header - the only valid value is application/jwt
request body (JWT): contains a signed JWT based on RFC 7515, which must follow the requirements below

Status list JWT definition `/issue`

The JSON Object Signing and Encryption (JOSE) header (based on RFC-7515) must contain the following header parameters:

{
  "typ": "JWT",
  "alg": "ES256",
  "kid": "1fb2c0f07f643b45cafeb53fb9d9eb34"
}

Parameter	Required or optional	Description
`typ`	Required	`typ` stands for ‘type’. You must set this value to be `JWT`. This is the media type of the complete JWT.
`alg`	Required	`alg` stands for ‘algorithm’. You must set this value to be `ES256`. This is the algorithm used to sign the JWT.
`kid`	Required	`kid` stands for ‘key ID’. This key ID must be present in your hosted JWKS. This is used to validate the JSON web signature (JWS).

Payload

The JWT payload must contain the following claims:

{
  "iss": "exampleclientIDabcd123",
  "iat": 1686920170,
  "jti": "62b45850-4c5c-4696-983a-af66450301d4",
  "statusExpiry": 1734709493
}

Claim	Required or optional	Description
`iss`	Required	`iss` stands for ‘issuer’. This is the `clientId` of the credential issuer service generated when registering as a client. Make sure you are using the correct `clientId` for your environment - production or integration.
`iat`	Required	`iat` stands for ‘issued at’. This is the UNIX timestamp when the request JWT was issued.
`jti`	Required	`jti` stands for ‘JWT ID’. This provides a unique identifier for the JWT. The Status List Service will validate the format provided to make sure it is a lowercase UUID.
`statusExpiry`	Required	The point after which the status expires. After this date the credential will be removed from the status list. `statusExpiry` must be equal to or later than the issued credential’s technical expiry time, known as the `validUntil` property. It may be useful to issue a status before the `validUntil` value is known. In this case, we recommend that you keep any resulting difference between `validUntil` and `statusExpiry` to a minimum. `statusExpiry` must be a number in seconds, formatted as a UNIX timestamp. The Status List Service does not support credentials lasting over 10 years.

Example Request

Below is an example of the post request signed and encoded as a JWT.

POST /issue HTTP/1.1
Host: <API.CRS.ACCOUNT.GOV.UK>
Content-Type: application/jwt
Accept: application/json

eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjgwODY4Nzk0LTM2MjYtNDNmOC05YTRkLWEwZDk4YWE3ZGE2NiJ9.eyJpc3MiOiJleGFtcGxlQ2xpZW50SWQxMjMzIiwiaWF0IjoxNzU5NDAyMjgzLCJqaXQiOiJiYzBmYmZmMy1jYjA0LTQyODYtYThiYS1mNDk1NmNjYmUyZDciLCJzdGF0dXNFeHBpcnkiOjE3Nzk2MTY1ODN9.yasAT3XhugXJhat_rVnVTkXdA3KS99DCZJV79WohLf18mkbKcuGlDVegmZFVCg6NOts0m3uI7Wet1QNGm07Xag

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "uri": "https://crs.account.gov.uk/b/A671FED3E9AD"
  "idx": 3,
}

Parameter	Description
`uri`	`uri` stands for ‘uniform resource identifier’. This is the uri to the status list endpoint in which the new credential has been stored. This will be formatted as `crs.account.gov.uk` for the production environment, and `crs.integration.account.gov.uk` for the integration environment.
`idx`	`idx` stands for ‘index’. This is the index at which the credential will be stored in the status list found on the uri.

This page was last reviewed on 22 October 2025. It needs to be reviewed again on 22 April 2026 .