Authentication
Bearer API keys, product-prefixed scopes, and OAuth client credentials.
API keys
All resource endpoints authenticate with a bearer API key issued from the Signature dashboard:
curl https://staging.withsignature.io/api/v1/organizations \
-H "Authorization: Bearer sk_live_..."| Prefix | Type | Use |
|---|---|---|
sk_live_ | Secret key, live mode | Server-side calls against production data. |
sk_test_ | Secret key, test mode | Server-side calls against test data. |
pk_live_ | Publishable key | Limited, client-safe operations. |
Keep secret keys server-side
sk_ keys grant write access to your organization's data. Never embed them
in client-side code, and rotate them from the dashboard if they leak.
Test-mode keys (sk_test_) operate on isolated test data — responses indicate
the mode via the key's livemode.
Scopes
Keys carry product-prefixed scopes. An endpoint requires at least one of its
listed scopes; missing scopes produce a permission_error with HTTP 403.
A key can only hand out scopes it holds itself. Creating an API key, or creating
or updating an OAuth application's requested_scopes, with a scope the calling
key lacks returns HTTP 403 with code scope_delegation_forbidden; param names
the field (scopes or requested_scopes).
| Scope | Grants |
|---|---|
platform:read | Read organizations, memberships, users, events. |
platform:write | Mutate platform resources. |
platform:api_keys:write | Create and revoke API keys. |
platform:webhook_endpoints:write | Manage webhook endpoints. |
brand:read | Read brand rules, palettes, fonts, checks. |
brand:write | Mutate brand resources. |
brand:rules:write | Manage brand rules. |
brand:palettes:write | Manage palettes. |
brand:checks:write | Run compliance checks. |
cms:read | Read icons, sets, slide assets, deployments. |
cms:write | Mutate CMS resources. |
cms:icons:write | Upload and manage icons. |
cms:slides:write | Manage slide assets and PPT sets. |
cms:deployments:write | Create deployments. |
buddy-packages:write | Upload, deploy and run Buddy packages with the Buddy CLI, as the person who issued the key. Not used by these APIs. |
OAuth 2.0 client credentials
Integrations that act on behalf of an OAuth application exchange client credentials for an access token (RFC 6749):
curl -X POST https://staging.withsignature.io/api/v1/oauth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials" \
-d "client_id=oa_client_..." \
-d "client_secret=oa_secret_..."Tokens can be inspected with POST /oauth/introspect and revoked with
POST /oauth/revoke. See the
OAuth endpoints reference for details.
Note that /oauth/token authenticates with the client credentials in the
request body — not a bearer header — and is exempt from idempotency and
rate-limit keying since those are keyed on API keys.