Skip to main content
Version: Cloud

Scoped OAuth credentials

Open Authorization (OAuth) scoped credentials let you interact with the Deeploy API securely and with fine-grained control. Unlike personal keys, which carry the full authorization of a user, scoped OAuth credentials limit access to a selected set of permissions (scopes). You can apply a credential globally across the organization or restrict it to specific workspaces.

Creating scoped OAuth credentials​

  1. Navigate to the Credentials section, then to Scoped OAuth credentials, and select + Add.
  2. In the menu that opens, provide a name and a validity period for the credential.
  3. Choose whether the credential applies to all or to specific workspaces.
  4. Select the scopes that the credential requires (see Scopes).
  5. Select + Add to create the credential and store the generated client secret securely.
info

Save the client secret carefully, since it's only shown once.

note

A created client is user scoped: all operations performed with it are treated as if the user performed them. A created client can therefore never have higher permissions than the user who created it. For example, if a user creates an OAuth client with use case owner permissions, that client will only be able to perform owner-level operations on use cases the creating user actually owns.

Generating a token​

To generate an access token from a client application, send a POST request to https://api.<domain>/oauth2/token using the client ID and client secret for authentication:

curl -k -X POST https://api.<domain>/oauth2/token \
  -u "<clientId>:<clientSecret>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials"

The returned bearer token can then authenticate API requests within the limits of the client's scopes.

To revoke a token before it expires, send a POST request to https://api.<domain>/oauth2/revoke using the client ID and client secret for authentication, along with the token you want to revoke:

curl -k -X POST "https://api.<domain>/oauth2/revoke" \
  -u "<clientId>:<clientSecret>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "token=<token>"

Managing credentials​

Created clients are listed in a table under Scoped OAuth credentials in the Credentials section. From the options menu of a table entry, you can perform the following actions, each of which requires confirmation:

  • Revoke — the credential isn't deleted, but becomes inoperative and can no longer authenticate.
  • Refresh — generates a new secret for the client. The previous secret stops working, so store the new secret securely and update it wherever you use the credential.
  • Delete — permanently removes the credential.
Beware

Keep client secrets confidential and never share them.

Beware

Deleting a credential can't be undone.

Scopes​

Scopes determine which resources a credential can access and which operations it can perform. For each scope level, you can select read, write, and delete operations independently.

note

Only organization admins and governance managers can select organization and user management scopes. When you scope a credential to specific workspaces, you can't select the organization and user management scopes.

Organization​
  • Read — view audit logs, controls and control frameworks, organization documents, approval rules, periodic reviews, vendors, integrations, the organization overview, and workspace overviews.
  • Write — create and edit controls and control frameworks, edit organization documents, create and edit approval rules, edit periodic reviews, create and edit vendors, create and edit integrations, and create workspaces.
  • Delete — delete controls and control frameworks, organization documents, approval rules, vendors, and integrations.
User management​
  • Read — view the users in the organization.
  • Write — invite new users and edit existing users.
  • Delete — remove users from the organization.
Workspace​
  • Read — view repositories, credentials, guardrails, workspace documentation, environment variables, job schedules, webhooks, workspace members, and workspace settings.
  • Write — create and edit repositories, create credentials, create guardrails, edit workspace documentation, edit environment variables, edit job schedules, edit webhooks, edit workspace members, and edit workspace settings and tags.
  • Delete — delete repositories, credentials, guardrails, workspace documentation, environment variables, job schedules, webhooks, workspace members, workspaces, and workspace tags.
Use case​
  • Read — view use cases, use case controls, and use case documentation.
  • Write — edit use cases, edit use case controls and change their status, update control frameworks, review use cases, edit use case documentation, and change the use case lifecycle stage.
  • Delete — delete use cases and use case documentation.
Deployment​
  • Read — view deployments, connected algorithm register, versions, container logs, events, monitoring, alert rules and alerts, custom metrics, traces and prediction logs, deployment authorization (tokens and OIDC subjects), and approval rules.
  • Write — create, edit, archive, restore, and cancel deployments; restore and rename versions; modify approvers and submit approval decisions; edit alert rules and update alert statuses; edit custom metrics; create traces; manage deployment authorization (tokens and OIDC subjects); and call inference, explain inference, and create or update evaluations and actuals.
  • Delete — delete deployments, algorithm register entries, alert rules, custom metrics, tokens, and OIDC subjects.