Skip to content
Port OS

Generate OAuth Client Secret

← HTTP API reference
View source specification ↗
POST /{namespace}/{principalType}/{principalId}/oauth-clients/{clientId}/secrets

Creates an additional secret and returns its plaintext once. Existing secrets remain active until explicitly revoked.

Required scope

Any authenticated access token

Path parameters

namespacestringRequired

Resource namespace. Port OS resource identifiers use port1.

pattern: "^port1$"

principalTypestringRequired

The type of principal that owns the OAuth client

principalIdstringRequired

The ID of the principal that owns the OAuth client

clientIdstringRequired

The ID of the OAuth client

Header parameters

Idempotency-KeystringRequired

Client-chosen key that makes a non-idempotent request retry-safe, following draft-ietf-httpapi-idempotency-key-header. A committed response is stored for 24 hours and replayed for the same principal, operation, key and payload. Missing key returns 400 IDEMPOTENCY_KEY_REQUIRED, a key longer than 255 characters returns 400 IDEMPOTENCY_KEY_INVALID, the same key with a different payload returns 422, and the same key while the first request is still in flight returns 409. Requests rolled back before external provider attempts do not consume the key. Group mutations retain terminal failed responses after provider attempts together with received provider truth; their operation contract defines these replayable outcomes.

minLength: 1

maxLength: 255

Request body

Required

Fields

CreateOAuthClientSecretRequest

Returns

200

Generate OAuth Client Secret response.

Fields

GenerateOAuthClientSecretResponse

Response headers

ETagstring

Opaque strong entity tag of the returned resource version. Send it back in `If-Match` on the next mutation of the same resource.

Errors

400 BAD_REQUEST

Invalid request path.

Check the request fields and any validation details, then correct the payload.

401 UNAUTHORIZED

Authentication required.

Obtain a valid access token, then retry.

403 FORBIDDEN

The caller cannot read or manage the selected OAuth client.

Check the linked account and its permissions for the device or resource.

404 NOT_FOUND

OAuth client or secret not found.

Verify the target identifier and that its endpoint or plugin route still exists.

409 IDEMPOTENCY_KEY_IN_FLIGHT

The key is in flight.

Check the device’s current mode or state. Retry only after the conflict is resolved.

422 IDEMPOTENCY_KEY_REUSED

The key was reused with a different payload.

Correct the rejected value using the constraints in the error details or request schema.

500 INTERNAL

Internal server error.

Retry with backoff only when the operation is safe to repeat. Include the error code when reporting persistent failures.