Authentication

JWT, API keys, and OAuth — when to use what

Share Of Model exposes three authentication schemes. Most integrations only ever need the first two.

Bearer JWT

The default for every Core API and Search API endpoint. Pass a short-lived JSON Web Token in the Authorization header:

Authorization: Bearer <ACCESS_TOKEN>

Tokens expire — when they do, the API returns 401. Get a new one either by exchanging your API key again, or by refreshing the token:

curl -X POST https://api.shareofmodel.ai/v1/auth/refresh_token \
  -H "Content-Type: application/json" \
  -d '{"token": "<CURRENT_ACCESS_TOKEN>"}'

API keys

Long-lived secrets you generate from the console, prefixed with sk-som-. Three scopes are available:

• User key — acts on behalf of a user across their organizations. Limited to 5 keys per user.
• Organization key — scoped to one organization.
• Workspace key — scoped to one workspace; safest for backend integrations.

Each key also carries a role, chosen at creation, which caps what the key can do — the organisation and workspace roles described in User Roles & Workspaces.

Exchange a key for a JWT — note the field is secret_key:

curl -X POST https://api.shareofmodel.ai/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"secret_key": "<YOUR_API_KEY>"}'

{ "token": "<ACCESS_TOKEN>" }

Keys can be rotated without being deleted — see the API Key endpoints in the API Reference. Rotation issues a new secret and invalidates the previous one, so you can roll a key without recreating the integration.

Store the API key as a server-side secret. Never ship it to a browser.

OAuth 2.0

Used only when connecting external Platform Accounts (Google Ads, TikTok). The flow runs through the console UI; you do not call the OAuth endpoints directly. See the Platform Integrations group in the API Reference for the resulting resources.