Authentication
Authorize API requests with a Bearer token, and how the device flow issues one.
Every non-public API request authenticates with an API token, sent as a
Bearer credential in the Authorization header:
Authorization: Bearer skh_live_<secret>A request acts as the account the token belongs to, limited to the token's
scopes. Public read endpoints under /api/v1/public/* need no token.
Token format
A token is an environment prefix followed by a 32-character secret. The prefix names the environment:
skh_live_…— a live token.skh_test_…— a test-environment token.
The full secret is shown once, when the token is created, and never again — copy it into a secret manager immediately. See API tokens for creating, scoping, and revoking tokens from the CLI and the dashboard.
Scopes
A token carries one or more scopes, so a credential can be granted only what it needs:
| Scope | Grants |
|---|---|
read | Resolve and read skills, versions, and registry membership. |
publish | Publish versions and move dist-tags. |
admin | Administrative actions, including promotion on review-required registries. |
Getting a token: the device flow
Interactive sign-in uses an OAuth-style device flow — a browserless
handshake that skillhub runs for you under skillhub login, and which any
client can drive directly over three endpoints:
Start a device authorization
POST /api/v1/auth/device with your client info returns a deviceCode, a short
human-readable userCode, a verifyUrl to open in a browser, an expiresAt,
and a poll interval (in seconds).
Approve in the browser
Open verifyUrl and enter the userCode to approve the request for your
account.
Poll for the token
POST /api/v1/auth/device/poll with the deviceCode, no faster than every
interval seconds. It returns { status: "pending" } until you approve, then
{ status: "approved", token, user } carrying the token secret (or denied /
expired).
Once you hold a token, send it as the Authorization: Bearer header on every
request. The CLI stores it for you (see Authenticate);
a raw HTTP client sends the header itself.
Managing tokens over HTTP
The same token lifecycle the dashboard drives is available on the API:
| Method & path | Purpose |
|---|---|
POST /api/v1/auth/tokens | Create a named, scoped token — optionally restricted to one registry or given an expiry. The secret is in the response, shown once. |
GET /api/v1/auth/tokens | List your tokens' metadata (never the secrets). |
DELETE /api/v1/auth/tokens/{tokenId} | Revoke a token. |
GET /api/v1/auth/whoami | Resolve the calling identity for the presented credential. |
Treat a token like a password: it acts as your account within its scopes. Never commit it, paste it into a chat, or print it in logs — keep it in a secret store and revoke it the moment it leaks.