Skip to content

Configure API access and scopes

An API key suits your own integration with a fixed workspace. OAuth suits applications where users sign in and explicitly grant access. Both methods restrict access through scopes and the granting user's current permissions.

Management under Settings → API access is available to workspace administrators with API-access permissions. Users can revoke their own OAuth grants under Connections → My authorizations.

Create an API key

  1. Open API access → API keys and create a key with a recognizable name.
  2. Select only the required scopes. For an initial read test, use connection:verify and agents:read.
  3. Choose an expiry: 30 days, 90 days, one year, a custom future date or explicitly no expiry. Prefer a bounded lifetime.
  4. Copy the full key from the one-time display into your application's protected credential store.
  5. Send it to the REST API in Authorization: Bearer <API_KEY>.

Rotate creates a new key and immediately invalidates the old one. Name, scopes and creator stay unchanged. Revoke permanently disables the key. Create a new key to change scopes. API keys require no callback URL and work independently of OAuth availability.

Register an OAuth application

  1. Open OAuth under API access and select Create application.
  2. Enter a name and 1–10 exact HTTPS callback URLs controlled by your application, without wildcards or fragments.
  3. Select allowed scopes and save.
  4. Copy the Client ID and the values under Configure OAuth: authorization URL, token URL, issuer and optional resource.

The application is bound to this workspace. It uses Authorization Code with PKCE S256, without a client secret. Every saved registration change and disabling the application revokes existing grants and tokens; users must sign in again.

Use OAuth in your application

  1. Generate a fresh PKCE verifier, its S256 challenge and random state for each sign-in.
  2. Open the authorization URL with response_type=code, client_id, exact redirect_uri, space-separated scope values, code_challenge, code_challenge_method=S256 and state.
  3. The user signs in to Nuvoca, reviews the workspace and permissions, then approves or denies access.
  4. Validate state at the callback. Exchange the code once using a form-encoded POST to the token URL with grant_type=authorization_code, client_id, redirect_uri, code and code_verifier.
  5. Store access and refresh tokens securely. Send the access token in a Bearer header to the REST API.

The resource is optional for REST. If supplied, it must exactly match the displayed REST value: issuer plus /api/external. MCP uses a different resource, issuer plus /mcp. Tokens cannot be exchanged between these surfaces. Client Credentials, DCR and OIDC are not supported sign-in methods for this access.

Renew tokens

An access token lasts five minutes. Renew it using a form-encoded POST to the token URL with grant_type=refresh_token, client_id and the current refresh_token, without a client secret.

Store both replacement tokens together and never reuse the previous refresh token. Serialize renewal requests: reusing a consumed refresh token revokes the entire grant. A grant lasts at most 24 hours from its original authorization; refresh does not extend that deadline. Sign in again after expiry, revocation or a failed refresh.

Choose scopes

Scope Allows
connection:verify Verify the bound workspace and granted permissions
agents:read List Agents
agents:configuration:read Read Agent configuration including prompts and selection catalogs
agents:write Create and configure Agents
flows:read / flows:write Read Agentic Flows and catalog / manage Flows
tools:read / tools:write Read tool configuration and catalogs / manage Agent tools
knowledge-bases:read / knowledge-bases:write Read / manage knowledge bases
documents:read / documents:write Read document metadata / add and delete documents
pre-processing:read / pre-processing:write Read pre-processing profiles and variables / configure profiles
post-processing:read / post-processing:write Read post-processing profiles and variables / configure profiles
phone-numbers:read / phone-numbers:write Read existing numbers / manage default assignments
call-summaries:read Read stored summaries and call details including phone numbers

Write scopes do not include read scopes. Select both for an editing workflow. A knowledge-base scope does not replace document permissions. Credential catalogs additionally require your current credential-read permission.

Existing keys and grants do not gain new scopes automatically. Access remains bound to one workspace and current user permissions, even while a token has not expired.

Revoke access and protect credentials

Revoke OAuth under Connections → My authorizations; authorized administrators can also revoke MCP grants under Tenant MCP connections. Revoke keys under API keys. Merely removing or forgetting access in a client does not replace revocation.

Keep tokens out of URLs, source code, screenshots and logs. MFA recovery does not automatically disable existing API keys or OAuth/MCP grants. Revoke affected machine credentials separately during a security incident.