PATCH/api/apis/{api_server_id}/scopes/{api_server_scope_id}Authenticated

Update an API scope

Changes the description shown to users for one of the API server's scopes and/or whether dynamically registered clients may be granted it (allow_dynamic_clients). The scope value is immutable: tokens already carry it, so renaming a scope means defining the new one and deleting the old one.

operationId patch_api_apis_api_server_id_scopes_api_server_scope_idAPI servers

Authentication & permissionsAuthenticated

Any authenticated user

Accepted credentials: Auth server session (refresh token cookie)cookie "refresh_token_<auth_server_app_id>"
Access token (cookie)cookie "access_token_<auth_server_app_id>"
Access token (Bearer)Authorization: Bearer <JWT>
Who may call: Any authenticated user
Notes: Organization owners/admins of the owning organization, the owning user of a user-owned API server, or platform administrators.

Path parameters

Name	Type	Description
api_server_id*	string	API server id
api_server_scope_id*	string (uuid)	Id of the API scope definition

Request body

Required

application/json

UpdateApiServerScopeRequestThe description and/or allow_dynamic_clients (at least one). The scope value is immutable (define a new scope and delete the old one to rename). Unknown keys are rejected.

Property	Type	Description
description	string	minLength: 1maxLength: 256
allow_dynamic_clients	boolean

JSONExample

"description""string"

"allow_dynamic_clients"true

Responses

application/json

ApiServerScopeResponse

Property	Type	Description
success*	true
scope*	ApiServerScope	An OAuth 2.0 scope value (RFC 6749 §3.3) an API server defines for itself, with the description shown to users. Clients request it on an authorization request whose RFC 8707 `resource` names the API server; it is granted on the access tokens minted for that API server.
api_server_scope_id*	string (uuid)
api_server_id*	string	minLength: 2maxLength: 64pattern: ^[a-z0-9_-]*$
scope*	string	minLength: 1maxLength: 128pattern: ^[\x21\x23-\x5B\x5D-\x7E]+$
description*	string	maxLength: 256
allow_dynamic_clients*	boolean
created_at*	number	minimum: 0
created_by*	string (uuid) \| null (uuid) \| null

JSONExample

"success"true

"scope"

"api_server_scope_id""123e4567-e89b-12d3-a456-426614174000"

"api_server_id""string"

"scope""string"

"description""string"

"allow_dynamic_clients"true

"created_at"1.5

"created_by""123e4567-e89b-12d3-a456-426614174000"

Example request

bashcurl

curl -X PATCH 'https://auth.schemavaults.com/api/apis/<api_server_id>/scopes/<api_server_scope_id>' \
  -b 'refresh_token_<auth_server_app_id>=<value>' \
  -H 'Content-Type: application/json' \
  -d '{
  "description": "string",
  "allow_dynamic_clients": true
}'

Other methods on this path

DELETEDelete an API scope

Authentication & permissionsAuthenticated

Path parameters

Request body

Responses

200The updated scope

400The request failed validation (issues lists the offending fields) or was refused by the handler

401No valid session cookie, access token cookie or bearer access token was presented, or the token was revoked

403The account is disabled, or the credential is valid but not allowed to perform this operation

404No such API server, or it defines no scope with that id

500Failed to update the scope

Example request

Other methods on this path