Secret Management

Endpoints for managing client secrets. Each OAuth client can have multiple secrets to support rotation without downtime.

GET /api/oauth-clients/{id}/secrets

List all secrets for a client.

Authentication: Required

Permissions Required: Superuser + token API feature

Path Parameters:

Parameter	Type	Description
id	string	Client UUID or client_id

Response:

{
  "_embedded": {
    "inf:oauth-client-secret": [
      {
        "_links": {
          "self": { "href": "/api/oauth-clients/client-uuid-123/secrets/secret-uuid-1" }
        },
        "id": "secret-uuid-1",
        "hint": "*****abc12345",
        "lastUsedAt": "2024-02-20T14:30:00.000Z",
        "oauthClientId": "client-uuid-123",
        "createdAt": "2024-01-15T10:00:00.000Z",
        "updatedAt": "2024-02-20T14:30:00.000Z"
      }
    ]
  }
}

Secret Values

The plaintext secret value is never returned in list or get responses. It is only returned once, immediately after creation.

---

POST /api/oauth-clients/{id}/secrets

Generate a new client secret. The plaintext secret is returned only in this response.

Authentication: Required

Permissions Required: Superuser + token API feature

Path Parameters:

Parameter	Type	Description
id	string	Client UUID or client_id

Payload: Empty

Response: 201 Created

{
  "id": "secret-uuid-2",
  "secret": "cs_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "hint": "*****n4o5p6",
  "oauthClientId": "client-uuid-123",
  "createdAt": "2024-02-23T10:00:00.000Z",
  "updatedAt": "2024-02-23T10:00:00.000Z"
}

Field	Description
secret	Plaintext secret (only returned here, stored as bcrypt hash)
hint	Last 8 characters prefixed with ***** for identification

One-Time Display

The plaintext secret value is only returned in this response. It is bcrypt-hashed before storage and cannot be retrieved later. Store it securely.

---

GET /api/oauth-clients/{oauthClientId}/secrets/{id}

Get a single secret's metadata.

Authentication: Required

Permissions Required: Superuser + token API feature

Path Parameters:

Parameter	Type	Description
oauthClientId	string	Client UUID or client_id
id	string	Secret UUID

Response:

{
  "id": "secret-uuid-1",
  "hint": "*****abc12345",
  "lastUsedAt": "2024-02-20T14:30:00.000Z",
  "oauthClientId": "client-uuid-123",
  "createdAt": "2024-01-15T10:00:00.000Z",
  "updatedAt": "2024-02-20T14:30:00.000Z"
}

---

PUT /api/oauth-clients/{oauthClientId}/secrets/{id}

Update a secret's metadata (e.g., hint).

Authentication: Required

Permissions Required: Superuser + token API feature

Path Parameters:

Parameter	Type	Description
oauthClientId	string	Client UUID or client_id
id	string	Secret UUID

Response: Updated secret object.

---

DELETE /api/oauth-clients/{oauthClientId}/secrets/{id}

Delete a client secret.

Authentication: Required

Permissions Required: Superuser + token API feature

Path Parameters:

Parameter	Type	Description
oauthClientId	string	Client UUID or client_id
id	string	Secret UUID

Response: 204 No Content

Active Sessions

Deleting a secret does not revoke tokens that were issued using it. Use the revoke endpoint to invalidate active tokens.