API authentication

The Gamut API authenticates with bearer tokens, named, revocable and expiring credentials tied to a user and an accessible workspace. They let automation and integrations act on the API without a browser session while retaining the same tenant, role and entitlement boundaries.

Creating a token

Create a named token from your account, select the exact workspace and choose a read-only or read/write scope. A token inherits the role and entitlements of the user who created it: it can do what that user can do within the selected workspace, and no more.

Write-enabled tokens require the user to re-enter their current password. Where MFA is enrolled, the current authenticator code is also required. This prevents an unattended browser session from silently creating durable write authority.

Shown once

A token’s secret value is shown only once, at creation. Copy it immediately and store it in a secrets manager. If you lose it, revoke the token and create a new one.

Using a token

Send the token as a bearer credential on each request:

GET /api/compass/v1/... HTTP/1.1
Host: run.gamutassure.com
Authorization: Bearer <your-token>

Bearer-authenticated requests are intended for server-to-server automation. Do not embed tokens in browsers, mobile apps or any client where users could extract them.

Managing tokens

You can:

• List your tokens to see their name, workspace, scope, expiry and recent use.
• Revoke a token immediately when it is no longer needed or may be exposed.

Revoking a token takes effect at once, any integration using it will stop being authorised.

Keeping tokens secure

• Store in a secrets manager, never in source control.
• Scope by user. Create tokens under a user whose role matches what the integration needs, apply least privilege.
• Scope by workspace. Use a separate token for each workspace boundary.
• Prefer read-only. Grant write scope only when the integration must change governance data.
• Use a short lifetime. Set an expiry appropriate to the integration and rotate before it.
• Rotate tokens periodically, and immediately if exposure is suspected.
• One token per integration, so you can revoke one without disrupting others.

Sessions vs. tokens

Interactive use of Gamut in the browser uses a signed-in session; programmatic use uses bearer tokens. For human sign-in, including single sign-on, see Users & roles.

Bearer tokens cannot manage account credentials, create other tokens or change their own security boundary. Account suspension, password reset and other qualifying account-security events revoke existing programmatic authority so retained credentials cannot outlive the account decision.

Next

• API overview: base URL and capabilities.
• Conventions & errors: request and response shape.