Skip to content

Gateway Tokens

Gateway token rotation and revocation operations

List active gateway tokens

GET /gateways/{gatewayId}/tokens

Code samples

curl -X GET https://localhost:9243/api/v0.9/gateways/{gatewayId}/tokens \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Accept: application/json'

Returns all active tokens for the specified gateway. Token hashes and salts are never exposed. Access is validated against the organization in the JWT token.

Authentication

Parameters

Name In Type Required Description
gatewayId path string true Gateway ID consisting of the handle (unique slug identifier) of the Gateway.
limit query integer false Maximum number of items to return per page.
offset query integer false Zero-based index of the first item to return.

Detailed descriptions

gatewayId: Gateway ID consisting of the handle (unique slug identifier) of the Gateway.

Example responses

200 Response

{
  "count": 0,
  "list": [
    {
      "id": "abc12345-f678-90de-f123-456789abcdef",
      "status": "active",
      "createdAt": "2025-10-14T10:30:00Z",
      "revokedAt": null
    }
  ],
  "pagination": {
    "total": 10,
    "offset": 0,
    "limit": 10
  }
}

401 Response

{
  "status": "error",
  "code": "UNAUTHORIZED",
  "message": "Authorization header is required, or the token is invalid or expired."
}

404 Response

{
  "status": "error",
  "code": "NOT_FOUND",
  "message": "The specified resource does not exist."
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_ERROR",
  "message": "An unexpected error occurred.",
  "trackingId": "4f1c6f2e-8a4b-4c93-b1de-9f2f6f0c2a11"
}

Responses

Status Meaning Description Schema
200 OK List of active tokens GatewayTokenListResponse
401 Unauthorized Unauthorized. Authentication credentials are missing or invalid. Error
404 Not Found Not Found. The specified resource does not exist. Error
500 Internal Server Error Internal Server Error. Error

Rotate gateway token

POST /gateways/{gatewayId}/tokens

Code samples

curl -X POST https://localhost:9243/api/v0.9/gateways/{gatewayId}/tokens \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Accept: application/json'

Generates a new authentication token for the gateway. The existing token remains active to enable zero-downtime rotation. Access is validated against the organization in the JWT token.

Authentication

Parameters

Name In Type Required Description
gatewayId path string true Gateway ID consisting of the handle (unique slug identifier) of the Gateway.

Detailed descriptions

gatewayId: Gateway ID consisting of the handle (unique slug identifier) of the Gateway.

Example responses

201 Response

{
  "id": "def45678-g901-23hi-j456-789012klmnop",
  "token": "REDACTED_TOKEN",
  "createdAt": "2025-10-15T14:20:00Z",
  "message": "New token generated successfully. Old token remains active until revoked."
}

400 Response

{
  "status": "error",
  "code": "VALIDATION_FAILED",
  "message": "The request failed validation.",
  "errors": [
    {
      "field": "<name of the offending field>",
      "message": "<reason this field failed validation>"
    }
  ]
}

401 Response

{
  "status": "error",
  "code": "UNAUTHORIZED",
  "message": "Authorization header is required, or the token is invalid or expired."
}

403 Response

{
  "status": "error",
  "code": "FORBIDDEN",
  "message": "You do not have permission to perform this action."
}

404 Response

{
  "status": "error",
  "code": "NOT_FOUND",
  "message": "The specified resource does not exist."
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_ERROR",
  "message": "An unexpected error occurred.",
  "trackingId": "4f1c6f2e-8a4b-4c93-b1de-9f2f6f0c2a11"
}

Responses

Status Meaning Description Schema
201 Created New token generated successfully TokenRotationResponse
400 Bad Request Bad Request. Invalid request or validation error. Error
401 Unauthorized Unauthorized. Authentication credentials are missing or invalid. Error
403 Forbidden Forbidden. The authenticated user does not have permission to access this resource. Error
404 Not Found Not Found. The specified resource does not exist. Error
500 Internal Server Error Internal Server Error. Error

Response Headers

Status Header Type Format Description
201 Location string uri URL of the newly created resource.

Revoke gateway token

DELETE /gateways/{gatewayId}/tokens/{tokenId}

Code samples

curl -X DELETE https://localhost:9243/api/v0.9/gateways/{gatewayId}/tokens/{tokenId} \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Accept: application/json'

Revokes a specific gateway token. Operation is idempotent - revoking an already-revoked token succeeds. Access is validated against the organization in the JWT token.

Authentication

Parameters

Name In Type Required Description
gatewayId path string true Gateway ID consisting of the handle (unique slug identifier) of the Gateway.
tokenId path string(uuid) true Token ID consisting of the UUID of the Token.

Detailed descriptions

gatewayId: Gateway ID consisting of the handle (unique slug identifier) of the Gateway.

tokenId: Token ID consisting of the UUID of the Token.

Example responses

200 Response

{
  "message": "Token revoked successfully"
}

400 Response

{
  "status": "error",
  "code": "VALIDATION_FAILED",
  "message": "The request failed validation.",
  "errors": [
    {
      "field": "<name of the offending field>",
      "message": "<reason this field failed validation>"
    }
  ]
}

401 Response

{
  "status": "error",
  "code": "UNAUTHORIZED",
  "message": "Authorization header is required, or the token is invalid or expired."
}

403 Response

{
  "status": "error",
  "code": "FORBIDDEN",
  "message": "You do not have permission to perform this action."
}

404 Response

{
  "status": "error",
  "code": "NOT_FOUND",
  "message": "The specified resource does not exist."
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_ERROR",
  "message": "An unexpected error occurred.",
  "trackingId": "4f1c6f2e-8a4b-4c93-b1de-9f2f6f0c2a11"
}

Responses

Status Meaning Description Schema
200 OK Token revoked successfully Inline
400 Bad Request Bad Request. Invalid request or validation error. Error
401 Unauthorized Unauthorized. Authentication credentials are missing or invalid. Error
403 Forbidden Forbidden. The authenticated user does not have permission to access this resource. Error
404 Not Found Not Found. The specified resource does not exist. Error
500 Internal Server Error Internal Server Error. Error

Response Schema

Status Code 200

Name Type Required Restrictions Description
message string false none none