Clients API reference

Enumerate OAuth Clients

GET /oauth-clients

Lists all OAuth clients for the authenticated user

Requires a signed user/session or the existing authenticated client flow. The anonymous DCR delegated device profile cannot invoke this operation.

Required scope

Any authenticated access token

Query parameters

nextTokenstring

Opaque token for the next page of results. Pass the continuation token returned by the previous response, unchanged. Omit it to start from the first page.

maxResultsinteger

Maximum number of results to return in one page. Defaults to 100. Values from 1 through 100 are accepted.

minimum: 1

maximum: 100

Default: 100

expandarray<string>

Expansion tokens that request related or computed fields for each result. When omitted, the response contains only the default, shallower set of fields for each result.

Returns

200

OAuth clients retrieved successfully

Fields

resultsarray<OAuthClient>Required

A list of registered OAuth clients.

An OAuth 2.0 client registration conforming to RFC 7591 with Port OS extensions.

idstringRequired

Stable query result identifier for the OAuth client. Mirrors clientId.

clientIdstringRequired

The unique identifier for the OAuth client

clientNamestringRequired

A human-readable string name of the client to be presented to the end-user during authorization. If omitted, the authorization server may display the raw "client_id" value to the end-user instead. See https://datatracker.ietf.org/doc/html/rfc7591#section-2

clientUristring

A URL string of a web page providing information about the client. If present, the server should display this URL to the end-user in a clickable fashion. See https://datatracker.ietf.org/doc/html/rfc7591#section-2

format: "uri"

logoUristring

A URL string that references a logo for the client. If present, the server should display this image to the end-user during approval. See https://datatracker.ietf.org/doc/html/rfc7591#section-2

format: "uri"

redirectUrisarray<string>

An array of redirection URI strings for use in redirect-based flows such as the authorization code and implicit flows. Clients using these flows must register their redirection URI values. See https://datatracker.ietf.org/doc/html/rfc7591#section-2

Itemstring: format: "uri"

allowedOriginsarray<string>

An array of authorized JavaScript origin strings. When set, the server validates the Origin header on token requests against this list. Origins are scheme + host (+ optional port), with no path.

Itemstring: format: "uri"

grantTypesarray<string>

An array of OAuth 2.0 grant type strings that the client can use at the token endpoint. The token endpoint refuses any other grant with `unauthorized_client`, and a refresh token is issued only to a client that registered refresh_token. Registration stores authorization_code and refresh_token (client_credentials for a private_key_jwt client) when the request omits grant types; a stored client with an empty list may use only authorization_code (the RFC 7591 default). See https://datatracker.ietf.org/doc/html/rfc7591#section-2

Itemstring: Allowed values
authorization_code
client_credentials
refresh_token
urn:ietf:params:oauth:grant-type:device_code

responseTypesarray<string>

An array of OAuth 2.0 response type strings that the client can use at the authorization endpoint. See https://datatracker.ietf.org/doc/html/rfc7591#section-2

Itemstring: Allowed values
code
token
id_token

tokenEndpointAuthMethodstring

A string indicating the requested authentication method for the token endpoint. Values defined by this specification are "client_secret_post", "client_secret_basic", "client_secret_jwt", "private_key_jwt", and "none". See https://datatracker.ietf.org/doc/html/rfc7591#section-2

Allowed values

client_secret_post
client_secret_basic
client_secret_jwt
private_key_jwt
none

tokenEndpointAuthSigningAlgstring

A string containing a JWS signing algorithm (alg value) that MUST be used for signing the JWT used to authenticate the client at the token endpoint for the "private_key_jwt" and "client_secret_jwt" authentication methods. See https://datatracker.ietf.org/doc/html/rfc7591#section-2

Allowed values

RS256
ES256

scopestring

A string containing a space-separated list of scope values that the client can use when requesting access tokens. Valid scopes are: endpoint:read, endpoint:write, message:read, message:send, secret:read, secret:write, principal:read, principal:write, subscription:read, subscription:write, access-control-rule:read, access-control-rule:write. Scopes are mapped to Cedar permissions (e.g., "endpoint:read" maps to "endpoint.read"). See https://datatracker.ietf.org/doc/html/rfc7591#section-2

scopesarray<OAuthScope>

List of OAuth scopes that this client can request (array representation of scope). This is a convenience field that represents the space-separated scope string as an array. Scopes are mapped to Cedar permissions (e.g., "endpoint:read" maps to "endpoint.read").

Itemstring: OAuth 2.0 scope values that can be requested by clients. Delegated REST scopes bound operations before the owning service evaluates resource policy. A scope is an upper bound, not a resource permission or an automatic Cedar grant. Each scope follows the pattern "resource:action" where resource indicates the resource type and action indicates the permitted operation (read, write, send, trigger).

contactsarray<string>

An array of strings representing ways to contact people responsible for this client, typically email addresses. The authorization server may make these contact addresses available to end-users for support requests for the client. See https://datatracker.ietf.org/doc/html/rfc7591#section-2

Itemstring: format: "email"

tosUristring

A URL string that points to a human-readable terms of service document for the client that describes a contractual relationship between the end-user and the client that the end-user accepts when authorizing the client. See https://datatracker.ietf.org/doc/html/rfc7591#section-2

format: "uri"

tosUriLocalizedobject

Localized versions of the terms of service URI using language tags as keys (BCP 47 format). The keys are language tags and values are the localized terms of service URIs. See https://datatracker.ietf.org/doc/html/rfc7591#section-2.2

policyUristring

A URL string that points to a human-readable privacy policy document that describes how the deployment organization collects, uses, retains, and discloses personal data. See https://datatracker.ietf.org/doc/html/rfc7591#section-2

format: "uri"

policyUriLocalizedobject

Localized versions of the privacy policy URI using language tags as keys (BCP 47 format). The keys are language tags and values are the localized privacy policy URIs. See https://datatracker.ietf.org/doc/html/rfc7591#section-2.2

clientSecretstring

The client secret string known only to the client and the authorization server. This secret is used for authenticating the client to the authorization server. This field is typically only returned during client registration and should not be included in GET responses for security reasons. See https://datatracker.ietf.org/doc/html/rfc7591#section-2.2

clientSecretExpiresAtinteger

An integer indicating the expiration time of the client secret, represented as the number of seconds since the Unix epoch (1970-01-01T00:00:00Z). A value of 0 indicates that the secret does not expire. See https://datatracker.ietf.org/doc/html/rfc7591#section-2.2

jwksUristring

A URL string referencing the client's JSON Web Key (JWK) Set document, which contains the client's public keys. These keys can be used by higher-level protocols that use signing or encryption. See https://datatracker.ietf.org/doc/html/rfc7591#section-2

format: "uri"

jwksOAuthClientJwks

The client's JSON Web Key Set document value, which contains the client's public keys. This parameter is intended to be used by clients that cannot use the "jwks_uri" parameter, such as native clients that cannot host public URLs. See https://datatracker.ietf.org/doc/html/rfc7591#section-2

softwareIdstring

A unique identifier string assigned by the client developer or software publisher used by registration endpoints to identify the client software to be dynamically registered. See https://datatracker.ietf.org/doc/html/rfc7591#section-2

softwareVersionstring

A version identifier string for the client software identified by "software_id". The value of the "software_version" should change on any update to the client software identified by the same "software_id". See https://datatracker.ietf.org/doc/html/rfc7591#section-2

ownerIdstring

The owner ID of the OAuth client (Port OS specific field)

createdAtstring

The timestamp when the OAuth client was created (Port OS specific field)

format: "date-time"

updatedAtstring

The timestamp when the OAuth client was last updated (Port OS specific field)

format: "date-time"

etagstringRequired

Opaque strong entity tag for optimistic concurrency.

requiresPkceboolean

Whether this client requires PKCE.

paginationContextPaginationContextRequired

errorsarray<Error>

Partial query errors collected while returning available results.

The one Port OS error shape, returned by every REST error response and every MCP tool error. `code` names the specific failure and `family` its broad class; both are closed enums, so clients branch on them and show `message`, which says what failed and what to do next.

familystringRequired

The broad class of an error. The family decides the HTTP status of a REST error, so clients can handle every code of a family alike.

codestringRequired

The specific error, one of a closed set of Port OS codes. Every REST error body, MCP tool error, batch item error and discovery item error uses this enum; each code belongs to an `ErrorFamily` that decides its HTTP status. Provider-specific codes are never codes: they travel in `details.providerCode`. New failure kinds are added here, never as free strings.

messagestringRequired

Plain-language description of the failure and the suggested next action.

detailsErrorDetails

Optional typed context for an error. Fields are additive and only populated when the error can safely expose that context to API clients.

errorsarray<SynchronizationItemError>

Every rejected item when a request that is validated item by item and applied atomically fails, such as a discovery `SynchronizationRequest` whose routes, group routes or relationships are rejected. Omitted for single-item failures.

One rejected discovery item of a `SynchronizationRequest`, keyed by the plugin-owned identity of the rejected item: `pluginRouteId` for a route or group route, or `relationshipExternalId` for a relationship. Exactly one of the two is set. It shares the `code`, `family`, `status` and `message` fields of `BatchItemError`; discovery items are keyed by plugin-owned identity because they carry no `requestId`. A request with any rejected item is rejected as a whole and lists every rejected item.

pluginRouteIdstring

Plugin-owned identifier of the rejected route or group route. Set unless the item is a relationship.

relationshipExternalIdstring

Plugin-owned `externalId` of the rejected relationship. Set only for relationship items.

interfacestring

Canonical capability interface name the failure applies to, when the failure is interface-specific.

versionstring

Declared capability interface version the failure applies to, when the failure is interface-specific.

codestringRequired

The specific error, one of a closed set of Port OS codes. Every REST error body, MCP tool error, batch item error and discovery item error uses this enum; each code belongs to an `ErrorFamily` that decides its HTTP status. Provider-specific codes are never codes: they travel in `details.providerCode`. New failure kinds are added here, never as free strings.

familystringRequired

The broad class of an error. The family decides the HTTP status of a REST error, so clients can handle every code of a family alike.

statusintegerRequired

HTTP-equivalent status code of the item failure.

minimum: 400

maximum: 599

messagestringRequired

Plain-language description of the failure and the suggested fix.

Errors

400 BAD_REQUEST

Invalid request payload

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

401 UNAUTHORIZED

Unauthorized - invalid or missing authentication token

Obtain a valid access token, then retry.

403 FORBIDDEN

Current OAuth client management permission denied.

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

500 INTERNAL

Internal server error

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

Upsert OAuth Client

View source specification ↗

POST /oauth-clients

Creates a server-identified OAuth client or fully replaces the client named by id. If-Match is required for replacement. Omitted writable metadata is cleared or defaulted; omitted clientSecret preserves the existing value. Idempotent responses are retained for 24 hours.

Required scope

Any authenticated access token

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

If-Matchstring

Required for a full replacement when the request identifies an existing resource. Send that resource's quoted strong etag from its last GET. A missing condition on a replacement returns 428 PRECONDITION_REQUIRED; a stale condition returns 412 PRECONDITION_FAILED. Omit this header when creating a new resource without an id. Wildcards are accepted only where the operation explicitly permits them.

minLength: 1

Request body

Required

Fields

clientNamestringRequired

A human-readable string name of the client to be presented to the end-user during authorization. If omitted, the authorization server may display the raw "client_id" value to the end-user instead. See https://datatracker.ietf.org/doc/html/rfc7591#section-2

clientUristring

A URL string of a web page providing information about the client. If present, the server should display this URL to the end-user in a clickable fashion. See https://datatracker.ietf.org/doc/html/rfc7591#section-2

format: "uri"

logoUristring

A URL string that references a logo for the client. If present, the server should display this image to the end-user during approval. See https://datatracker.ietf.org/doc/html/rfc7591#section-2

format: "uri"

redirectUrisarray<string>

An array of redirection URI strings for use in redirect-based flows such as the authorization code and implicit flows. Clients using these flows must register their redirection URI values. See https://datatracker.ietf.org/doc/html/rfc7591#section-2

Itemstring: format: "uri"

allowedOriginsarray<string>

An array of authorized JavaScript origin strings. When set, the server validates the Origin header on token requests against this list. Origins are scheme + host (+ optional port), with no path.

Itemstring: format: "uri"

grantTypesarray<string>

An array of OAuth 2.0 grant type strings that the client can use at the token endpoint, each at most once. The token endpoint refuses any other grant with `unauthorized_client`, and a refresh token is issued only to a client that registered refresh_token. authorization_code requires redirect_uris; client_credentials requires a client_secret_post, client_secret_basic or private_key_jwt client. When omitted, the server registers authorization_code and refresh_token, or client_credentials for a private_key_jwt client, and returns the registered list (RFC 7591 lets the server substitute values). See https://datatracker.ietf.org/doc/html/rfc7591#section-2

uniqueItems: true

Default: ["authorization_code","refresh_token"]

Itemstring: Allowed values
authorization_code
client_credentials
refresh_token
urn:ietf:params:oauth:grant-type:device_code

responseTypesarray<string>

An array of OAuth 2.0 response type strings that the client can use at the authorization endpoint. See https://datatracker.ietf.org/doc/html/rfc7591#section-2

Itemstring: Allowed values
code
token
id_token

tokenEndpointAuthMethodstring

A string indicating the requested authentication method for the token endpoint. Values defined by this specification are "client_secret_post", "client_secret_basic", "client_secret_jwt", "private_key_jwt", and "none". See https://datatracker.ietf.org/doc/html/rfc7591#section-2

Default: client_secret_post

Allowed values

client_secret_post
client_secret_basic
client_secret_jwt
private_key_jwt
none

tokenEndpointAuthSigningAlgstring

A string containing a JWS signing algorithm (alg value) that MUST be used for signing the JWT used to authenticate the client at the token endpoint for the "private_key_jwt" and "client_secret_jwt" authentication methods. See https://datatracker.ietf.org/doc/html/rfc7591#section-2

Allowed values

RS256
ES256

scopesarray<OAuthScope>

List of OAuth scopes that this client can request. This is the primary field for specifying scopes. Scopes are mapped to Cedar permissions (e.g., "endpoint:read" maps to "endpoint.read"). See https://datatracker.ietf.org/doc/html/rfc7591#section-2

Itemstring: OAuth 2.0 scope values that can be requested by clients. Delegated REST scopes bound operations before the owning service evaluates resource policy. A scope is an upper bound, not a resource permission or an automatic Cedar grant. Each scope follows the pattern "resource:action" where resource indicates the resource type and action indicates the permitted operation (read, write, send, trigger).

contactsarray<string>

An array of strings representing ways to contact people responsible for this client, typically email addresses. The authorization server may make these contact addresses available to end-users for support requests for the client. See https://datatracker.ietf.org/doc/html/rfc7591#section-2

Itemstring: format: "email"

tosUristring

A URL string that points to a human-readable terms of service document for the client that describes a contractual relationship between the end-user and the client that the end-user accepts when authorizing the client. See https://datatracker.ietf.org/doc/html/rfc7591#section-2

format: "uri"

policyUristring

A URL string that points to a human-readable privacy policy document that describes how the deployment organization collects, uses, retains, and discloses personal data. See https://datatracker.ietf.org/doc/html/rfc7591#section-2

format: "uri"

jwksUristring

A URL string referencing the client's JSON Web Key (JWK) Set document, which contains the client's public keys. These keys can be used by higher-level protocols that use signing or encryption. See https://datatracker.ietf.org/doc/html/rfc7591#section-2

format: "uri"

jwksOAuthClientJwks

The client's JSON Web Key Set document value, which contains the client's public keys. This parameter is intended to be used by clients that cannot use the "jwks_uri" parameter, such as native clients that cannot host public URLs. See https://datatracker.ietf.org/doc/html/rfc7591#section-2

softwareIdstring

A unique identifier string assigned by the client developer or software publisher used by registration endpoints to identify the client software to be dynamically registered. See https://datatracker.ietf.org/doc/html/rfc7591#section-2

softwareVersionstring

A version identifier string for the client software identified by "software_id". The value of the "software_version" should change on any update to the client software identified by the same "software_id". See https://datatracker.ietf.org/doc/html/rfc7591#section-2

idstring

Existing server-assigned client ID; unknown IDs return 404.

clientSecretstring

Optional secret replacement. Omission preserves an existing secret; creations generate one for confidential clients.

writeOnly: true

minLength: 1

requiresPkceboolean

Whether this client requires PKCE.

Default: false

Returns

200

Stored OAuth client with its current strong etag. Plaintext is present only on creation or explicit secret replacement, including exact request replay.

Fields

(payload)any: Stored OAuth client including its new etag. clientSecret is present only on creation or explicit secret replacement, including an exact idempotent replay.

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 payload

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

401 UNAUTHORIZED

Unauthorized - invalid or missing authentication token

Obtain a valid access token, then retry.

403 FORBIDDEN

Current OAuth client management permission denied.

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

404 NOT_FOUND

Client ID does not exist.

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.

412 PRECONDITION_FAILED

The client version is stale.

Inspect the returned code and family and follow the error handling guide.

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.

428 PRECONDITION_REQUIRED

If-Match is required for replacement.

Inspect the returned code and family and follow the error handling guide.

500 INTERNAL

Internal server error

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

Get OAuth Client

View source specification ↗

GET /{namespace}/{principalType}/{principalId}/oauth-clients/{clientId}

Retrieves details of a specific OAuth client

Requires a signed user/session or the existing authenticated client flow. The anonymous DCR delegated device profile cannot invoke this operation.

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 to retrieve

Query parameters

expandarray<string>: Expansion tokens that request related or computed fields for the returned resource.

Returns

200

OAuth client retrieved successfully

Fields

idstringRequired

Stable query result identifier for the OAuth client. Mirrors clientId.

clientIdstringRequired

The unique identifier for the OAuth client

clientNamestringRequired

A human-readable string name of the client to be presented to the end-user during authorization. If omitted, the authorization server may display the raw "client_id" value to the end-user instead. See https://datatracker.ietf.org/doc/html/rfc7591#section-2

clientUristring

A URL string of a web page providing information about the client. If present, the server should display this URL to the end-user in a clickable fashion. See https://datatracker.ietf.org/doc/html/rfc7591#section-2

format: "uri"

logoUristring

A URL string that references a logo for the client. If present, the server should display this image to the end-user during approval. See https://datatracker.ietf.org/doc/html/rfc7591#section-2

format: "uri"

redirectUrisarray<string>

An array of redirection URI strings for use in redirect-based flows such as the authorization code and implicit flows. Clients using these flows must register their redirection URI values. See https://datatracker.ietf.org/doc/html/rfc7591#section-2

Itemstring: format: "uri"

allowedOriginsarray<string>

An array of authorized JavaScript origin strings. When set, the server validates the Origin header on token requests against this list. Origins are scheme + host (+ optional port), with no path.

Itemstring: format: "uri"

grantTypesarray<string>

An array of OAuth 2.0 grant type strings that the client can use at the token endpoint. The token endpoint refuses any other grant with `unauthorized_client`, and a refresh token is issued only to a client that registered refresh_token. Registration stores authorization_code and refresh_token (client_credentials for a private_key_jwt client) when the request omits grant types; a stored client with an empty list may use only authorization_code (the RFC 7591 default). See https://datatracker.ietf.org/doc/html/rfc7591#section-2

Itemstring: Allowed values
authorization_code
client_credentials
refresh_token
urn:ietf:params:oauth:grant-type:device_code

responseTypesarray<string>

An array of OAuth 2.0 response type strings that the client can use at the authorization endpoint. See https://datatracker.ietf.org/doc/html/rfc7591#section-2

Itemstring: Allowed values
code
token
id_token

tokenEndpointAuthMethodstring

A string indicating the requested authentication method for the token endpoint. Values defined by this specification are "client_secret_post", "client_secret_basic", "client_secret_jwt", "private_key_jwt", and "none". See https://datatracker.ietf.org/doc/html/rfc7591#section-2

Allowed values

client_secret_post
client_secret_basic
client_secret_jwt
private_key_jwt
none

tokenEndpointAuthSigningAlgstring

A string containing a JWS signing algorithm (alg value) that MUST be used for signing the JWT used to authenticate the client at the token endpoint for the "private_key_jwt" and "client_secret_jwt" authentication methods. See https://datatracker.ietf.org/doc/html/rfc7591#section-2

Allowed values

RS256
ES256

scopestring

A string containing a space-separated list of scope values that the client can use when requesting access tokens. Valid scopes are: endpoint:read, endpoint:write, message:read, message:send, secret:read, secret:write, principal:read, principal:write, subscription:read, subscription:write, access-control-rule:read, access-control-rule:write. Scopes are mapped to Cedar permissions (e.g., "endpoint:read" maps to "endpoint.read"). See https://datatracker.ietf.org/doc/html/rfc7591#section-2

scopesarray<OAuthScope>

List of OAuth scopes that this client can request (array representation of scope). This is a convenience field that represents the space-separated scope string as an array. Scopes are mapped to Cedar permissions (e.g., "endpoint:read" maps to "endpoint.read").

Itemstring: OAuth 2.0 scope values that can be requested by clients. Delegated REST scopes bound operations before the owning service evaluates resource policy. A scope is an upper bound, not a resource permission or an automatic Cedar grant. Each scope follows the pattern "resource:action" where resource indicates the resource type and action indicates the permitted operation (read, write, send, trigger).

contactsarray<string>

An array of strings representing ways to contact people responsible for this client, typically email addresses. The authorization server may make these contact addresses available to end-users for support requests for the client. See https://datatracker.ietf.org/doc/html/rfc7591#section-2

Itemstring: format: "email"

tosUristring

A URL string that points to a human-readable terms of service document for the client that describes a contractual relationship between the end-user and the client that the end-user accepts when authorizing the client. See https://datatracker.ietf.org/doc/html/rfc7591#section-2

format: "uri"

tosUriLocalizedobject

Localized versions of the terms of service URI using language tags as keys (BCP 47 format). The keys are language tags and values are the localized terms of service URIs. See https://datatracker.ietf.org/doc/html/rfc7591#section-2.2

policyUristring

A URL string that points to a human-readable privacy policy document that describes how the deployment organization collects, uses, retains, and discloses personal data. See https://datatracker.ietf.org/doc/html/rfc7591#section-2

format: "uri"

policyUriLocalizedobject

Localized versions of the privacy policy URI using language tags as keys (BCP 47 format). The keys are language tags and values are the localized privacy policy URIs. See https://datatracker.ietf.org/doc/html/rfc7591#section-2.2

clientSecretstring

The client secret string known only to the client and the authorization server. This secret is used for authenticating the client to the authorization server. This field is typically only returned during client registration and should not be included in GET responses for security reasons. See https://datatracker.ietf.org/doc/html/rfc7591#section-2.2

clientSecretExpiresAtinteger

An integer indicating the expiration time of the client secret, represented as the number of seconds since the Unix epoch (1970-01-01T00:00:00Z). A value of 0 indicates that the secret does not expire. See https://datatracker.ietf.org/doc/html/rfc7591#section-2.2

jwksUristring

A URL string referencing the client's JSON Web Key (JWK) Set document, which contains the client's public keys. These keys can be used by higher-level protocols that use signing or encryption. See https://datatracker.ietf.org/doc/html/rfc7591#section-2

format: "uri"

jwksOAuthClientJwks

The client's JSON Web Key Set document value, which contains the client's public keys. This parameter is intended to be used by clients that cannot use the "jwks_uri" parameter, such as native clients that cannot host public URLs. See https://datatracker.ietf.org/doc/html/rfc7591#section-2

softwareIdstring

A unique identifier string assigned by the client developer or software publisher used by registration endpoints to identify the client software to be dynamically registered. See https://datatracker.ietf.org/doc/html/rfc7591#section-2

softwareVersionstring

A version identifier string for the client software identified by "software_id". The value of the "software_version" should change on any update to the client software identified by the same "software_id". See https://datatracker.ietf.org/doc/html/rfc7591#section-2

ownerIdstring

The owner ID of the OAuth client (Port OS specific field)

createdAtstring

The timestamp when the OAuth client was created (Port OS specific field)

format: "date-time"

updatedAtstring

The timestamp when the OAuth client was last updated (Port OS specific field)

format: "date-time"

etagstringRequired

Opaque strong entity tag for optimistic concurrency.

requiresPkceboolean

Whether this client requires PKCE.

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 payload

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

401 UNAUTHORIZED

Unauthorized - invalid or missing authentication token

Obtain a valid access token, then retry.

403 FORBIDDEN

Current OAuth client management permission denied.

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

404 NOT_FOUND

OAuth client not found

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

500 INTERNAL

Internal server error

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

Delete OAuth Client

View source specification ↗

DELETE /{namespace}/{principalType}/{principalId}/oauth-clients/{clientId}

Deletes an OAuth client. This permanently removes the OAuth client and invalidates all associated tokens. This action cannot be undone.

Requires a signed user/session or the existing authenticated client flow. The anonymous DCR delegated device profile cannot invoke this operation.

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 to delete

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

If-MatchstringRequired

The quoted strong entity tag of the resource the client last read (its `etag` field or `ETag` response header). The mutation is applied only when it still matches: a stale value returns 412 PRECONDITION_FAILED and a missing header returns 428 PRECONDITION_REQUIRED. Wildcards are accepted only where the operation explicitly permits them.

minLength: 1

Returns

200

OAuth client deleted successfully

No response body.

Errors

400 BAD_REQUEST

Invalid request payload

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

401 UNAUTHORIZED

Unauthorized - invalid or missing authentication token

Obtain a valid access token, then retry.

403 FORBIDDEN

Current OAuth client management permission denied.

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

404 NOT_FOUND

OAuth client 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.

412 PRECONDITION_FAILED

The client version is stale.

Inspect the returned code and family and follow the error handling guide.

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.

428 PRECONDITION_REQUIRED

If-Match is required.

Inspect the returned code and family and follow the error handling guide.

500 INTERNAL

Internal server error

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

List OAuth Client Secrets

View source specification ↗

GET /{namespace}/{principalType}/{principalId}/oauth-clients/{clientId}/secrets

Lists active masked secrets for the selected OAuth client. Plaintext and hashes are never returned.

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

Query parameters

nextTokenstring

Opaque token for the next page of results. Pass the continuation token returned by the previous response, unchanged. Omit it to start from the first page.

maxResultsinteger

Maximum number of results to return in one page. Defaults to 100. Values from 1 through 100 are accepted.

minimum: 1

maximum: 100

Default: 100

Returns

200

List OAuth Client Secrets response.

Fields

resultsarray<OAuthClientSecretInfo>Required

Active masked OAuth client secret metadata. No plaintext or hash is returned.

idstringRequired: Opaque child identifier scoped to the selected OAuth client.
clientIdstringRequired: Full OAuth client identifier.
maskedPreviewstringRequired: Masked preview that cannot be used to authenticate.
createdAtstringRequired: Creation timestamp, or an empty string when not recorded.
etagstringRequired: Strong entity tag of this immutable secret metadata.

paginationContextPaginationContextRequired

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.

500 INTERNAL

Internal server error.

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

Generate OAuth Client Secret

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

Returns

200

Generate OAuth Client Secret response.

Fields

(payload)any: Created secret metadata and plaintext returned only for its creation or exact idempotent replay.

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.

Revoke OAuth Client Secret

View source specification ↗

DELETE /{namespace}/{principalType}/{principalId}/oauth-clients/{clientId}/secrets/{secretId}

Permanently revokes one secret belonging to the selected OAuth client. Other secrets remain active.

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

secretIdstringRequired

The ID of the OAuth client secret

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

If-MatchstringRequired

The quoted strong entity tag of the resource the client last read (its `etag` field or `ETag` response header). The mutation is applied only when it still matches: a stale value returns 412 PRECONDITION_FAILED and a missing header returns 428 PRECONDITION_REQUIRED. Wildcards are accepted only where the operation explicitly permits them.

minLength: 1

Returns

200

Revoke OAuth Client Secret response.

No response body.

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.

412 PRECONDITION_FAILED

The secret version is stale.

Inspect the returned code and family and follow the error handling guide.

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.

428 PRECONDITION_REQUIRED

If-Match is required.

Inspect the returned code and family and follow the error handling guide.

500 INTERNAL

Internal server error.

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

Get OAuth Client Secret

View source specification ↗

GET /{namespace}/{principalType}/{principalId}/oauth-clients/{clientId}/secrets/{secretId}

Reads immutable masked secret metadata and its strong etag. Plaintext and hashes are never returned.

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

secretIdstringRequired

The ID of the OAuth client secret

Returns

200

Secret metadata.

Fields

idstringRequired: Opaque child identifier scoped to the selected OAuth client.
clientIdstringRequired: Full OAuth client identifier.
maskedPreviewstringRequired: Masked preview that cannot be used to authenticate.
createdAtstringRequired: Creation timestamp, or an empty string when not recorded.
etagstringRequired: Strong entity tag of this immutable secret metadata.

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

403 FORBIDDEN

Current OAuth client management permission denied.

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.