Signing Keys

The Signing Keys service provides a way to manage signing keys for JWTs and provide JWKS endpoints.

The Signing Key Model

The Signing Key model represents a signing key that can be used to sign JWTs. It contains the following properties:

Properties

Name
id
Type
string
Description
The unique identifier for the signing key (internal).
Name
kid
Type
string
Description
The Key ID (kid) is a unique identifier for the key. It is used to match a specific key in a JWKS endpoint.
Name
is_active
Type
boolean
Description
Indicates whether the signing key is active and can be used for signing JWTs.

Name

public_key

Type

object

Description

The public key information, including the Key ID (kid), key type (kty), algorithm (alg), and the public key itself (n and e for RSA, x and y for EC).

{
  kid: string; // Key ID
  kty: string; // Key type (e.g., RSA, EC)
  alg: string; // Algorithm (e.g., RS256, ES256)
  n?: string;  // RSA modulus (optional)
  e?: string;  // RSA exponent (optional)
  x?: string;  // EC x coordinate (optional)
  y?: string;  // EC y coordinate (optional)
}

Name
created_at
Type
string
Description
The date and time when the signing key was created.
Name
updated_at
Type
string
Description
The date and time when the signing key was last updated.

GET/api/v1/admin/signing-keys

List signing keys

Retrieve a paginated list of signing keys.

Optional attributes

Name
pagination[per_page]
Type
integer
Description
Max number of clients per page (default 10).
Name
pagination[page]
Type
integer
Description
Page number to return (default 1).
Name
filter[kid]
Type
string
Description
Filter by kid.
Name
order[kid]
Type
string
Description
ASC | DESC. Sort by creation time.
Name
order[created_at]
Type
string
Description
ASC | DESC. Sort by creation time.
Name
order[updated_at]
Type
string
Description
ASC | DESC. Sort by update time.
Name
order[retiredAt]
Type
string
Description
ASC | DESC. Sort by update time.

Request

GET

/v1/admin/signing-keys

  curl -G https://api.account.raha.af/api/v1/admin/signing-keys \
  -H "Authorization: Bearer {token}" \
  -d per_page=10 \
  -d page=1

Response

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "kid": "kid-example-123",
      "is_active": true,
      "public_key": {
        "kid": "kid-example-123",
        "kty": "RSA",
        "alg": "RS256",
        "n": "base64url-encoded-modulus",
        "e": "base64url-encoded-exponent"
      },
      "created_at": "2023-01-01T00:00:00Z",
      "updated_at": "2023-01-01T00:00:00Z"
    },
    {
          "id": "223e4567-e89b-12d3-a456-426614174001",
          "kid": "kid-example-456",
          "is_active": false,
          //...
    }
  ],
  "meta": {
    "page": 1,
    "from": 1,
    "to": 10,
    "last_page": 25,
    "per_page": 10,
    "total": 249
  }
}

POST/api/v1/admin/signing-keys

Create a signing key

Create a new signing key. The newly created key will be inactive by default.

Body parameters

Empty

Request

POST

/v1/admin/signing-keys

  curl -X POST https://api.account.raha.af/api/v1/admin/signing-keys \
  -H "Authorization: Bearer {token}"

Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "kid": "kid-example-123",
  "is_active": false,
  "public_key": {
    "kid": "kid-example-123",
    "kty": "RSA",
    "alg": "RS256",
    "n": "base64url-encoded-modulus",
    "e": "base64url-encoded-exponent"
  },
  "created_at": "2023-01-01T00:00:00Z",
  "updated_at": "2023-01-01T00:00:00Z"
}

POST/api//v1/admin/signing-keys/{id}/activate

Activate a signing key

Activate a signing key. Only one signing key can be active at a time. Activating a new key will deactivate the currently active key.

Path parameters

Name
id
Type
string
Description
The unique identifier of the signing key to activate.

Request

POST

/api/v1/admin/signing-keys/{id}/activate

  curl -X POST https://api.account.raha.af/api/v1/admin/signing-keys/123e4567-e89b-12d3-a456-426614174000/activate \
  -H "Authorization: Bearer {token}"

Response

Empty