Authentication

All requests to the SuiteOp API authenticate with a Bearer token in the Authorization header. There are two kinds of token:

API keys (sk_live_… / sk_test_…) — long-lived machine credentials that act as a member of your organization. This page covers these.
OAuth 2.1 access tokens — tokens an app or AI assistant obtains after a person authorizes it. Use these when an application acts on a specific user’s behalf. See OAuth 2.1 user-delegated access.

Both are presented the same way — as a Bearer token.

Key Format

Authorization: Bearer sk_live_your_key_here

The Bearer scheme is case-insensitive.

Key Anatomy

Part	Example	Meaning
Prefix	`sk_`	Always present on API keys
Environment	`live_` or `test_`	Production vs sandbox
Secret	`abc123…`	40+ random characters

sk_live_ keys reach production data. Keep them out of source control and client-side code.
sk_test_ keys are for development and testing. They operate against your organization’s data in sandbox mode.

Scopes

Each key is issued with a set of permission scopes. Scopes follow a resource:action pattern (for example tasks:read, tasks:write, reservations:read). A request that requires a scope the key does not have returns a 403 authorization_error.

Select the minimum scopes your integration needs when creating a key. You cannot add scopes to an existing key; create a new key with the updated scope set.

Key Lifecycle

Action	How
Create	Settings → API Keys → Create API Key
View	Shown once at creation; not retrievable afterwards
Revoke	Settings → API Keys → Revoke
Rotate	Revoke old key, create new key, update your integration

Keys can be created with no expiry or a fixed lifetime (30 days, 90 days, or 1 year); revoke any key that is no longer in use. For the full step-by-step on creating, scoping, monitoring, and revoking keys from the dashboard, see Managing API Keys.

401 vs 403

Status	Meaning
`401 authentication_error`	Key is missing, malformed, revoked, or belongs to a different organization
`403 authorization_error`	Key is valid but lacks the required scope for this operation

Security Practices

Server-side only. Never embed API keys in browser JavaScript, mobile apps, or any client-side code. Keys are long-lived bearer tokens with full API access within their scopes.
Environment variables. Load keys from environment variables or a secrets manager at runtime.
Rotate on suspicion. If a key may have been exposed, revoke it immediately and issue a new one.
Scope minimally. A key used only for reading reservations should not have tasks:write.