Skip to main content

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:

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.

Request header

Your request to the endpoint must include:

  • AWS SigV4 HTTP headers to authenticate your request
  • the Content-Type header where the only valid value is application/jwt

Request body

You must include a signed JWT based on RFC 7515 that follows the requirements shown in the example request.

Idempotent requests

Identical requests using the same jti will return the same idx and uri as the original successful request during a limited window. The Status List Service uses this window to deal with issues like connection problems or retries after a timeout. You should not use this window as a method to query existing statuses.

You must use unique jti values for each new status you wish to issue.

If you send a request with a previously used jti but a different statusExpiry, the service will return a 400 BAD_REQUEST error. You must generate a new jti for the new request.

If two requests with the same iss and jti arrive at exactly the same time, the service will return a 409 CONFLICT error for the second request. Retry after a short delay.

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, in seconds.
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 status 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 1 year.

Example request

This is an example of a POST request signed and encoded as a JWT.

POST /issue HTTP/2
Host: api.crs.dev.account.gov.uk
Authorization: AWS4-HMAC-SHA256 Credential=ASIAQWERTYUIOP123456/20260819/eu-west-2/execute-api/aws4_request, SignedHeaders=content-type;host;x-amz-date;x-amz-security-token, Signature=abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890
x-amz-security-token: <AWS_SESSION_TOKEN>
X-Amz-Date: 20260819T143001Z
Content-Type: application/jwt

eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjgwODY4Nzk0LTM2MjYtNDNmOC05YTRkLWEwZDk4YWE3ZGE2NiJ9.eyJpc3MiOiJleGFtcGxlQ2xpZW50SWQxMjMzIiwiaWF0IjoxNzU5NDAyMjgzLCJqaXQiOiJiYzBmYmZmMy1jYjA0LTQyODYtYThiYS1mNDk1NmNjYmUyZDciLCJzdGF0dXNFeHBpcnkiOjE3Nzk2MTY1ODN9.yasAT3XhugXJhat_rVnVTkXdA3KS99DCZJV79WohLf18mkbKcuGlDVegmZFVCg6NOts0m3uI7Wet1QNGm07Xag

Example response

This is an example of a response from the /issue endpoint:

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 status can be 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 status in the list can be checked.
This page was last reviewed on 5 October 2026. It needs to be reviewed again on 5 April 2027 by the page owner #di-mobile-wallet-tech-docs .