Skip to main content

​
Overview

The Tank Registry API supports two authentication methods:
  1. API Keys (recommended for CLI and automation)
  2. Session Cookies (for web browser access)
Most API consumers use API key authentication with Bearer tokens.

​
API Keys

API keys are prefixed with tank_ and provide programmatic access to the registry.

​
Key Properties

  • Format: tank_ followed by random characters
  • Expiration: Configurable (default 90 days for CLI tokens)
  • Rate Limit: Configurable per key (default 1000 requests/day)
  • Scopes: Optional permission scopes (e.g., skills:publish)

​
Using API Keys

Include the API key in the Authorization header: 
Authorization: Bearer tank_your_api_key_here
Example: 
curl -H "Authorization: Bearer tank_abc123" \
  https://registry.tank.dev/api/v1/skills/@tank/hello-world

​
CLI OAuth Flow

The tank login command uses a 3-step OAuth flow to obtain an API key.

​
Step 1: Start OAuth Session

Endpoint: POST /api/v1/cli-auth/start The CLI initiates authentication by creating a session.

​
Request

​
state
string
required
Random state string generated by CLI for CSRF protection
{
  "state": "random_state_string_generated_by_cli"
}

​
Response

​
authUrl
string
URL for the user to visit in their browser
​
sessionCode
string
Unique session identifier for polling
{
  "authUrl": "https://registry.tank.dev/cli-login?session=sess_abc123",
  "sessionCode": "sess_abc123"
}
Example: 
curl -X POST https://registry.tank.dev/api/v1/cli-auth/start \
  -H "Content-Type: application/json" \
  -d '{"state":"random_csrf_token"}'

​
Step 2: User Authorization

Endpoint: POST /api/v1/cli-auth/authorize The user visits authUrl in their browser, logs in via GitHub OAuth, and authorizes the CLI.
This step is performed in the browser with a session cookie. The CLI does not call this endpoint directly.

​
Request

​
sessionCode
string
required
Session code from Step 1
{
  "sessionCode": "sess_abc123"
}

​
Response

​
success
boolean
Indicates whether authorization succeeded
{
  "success": true
}

​
Step 3: Exchange for API Key

Endpoint: POST /api/v1/cli-auth/exchange The CLI polls this endpoint until the user completes authorization.

​
Request

​
sessionCode
string
required
Session code from Step 1
​
state
string
required
Same state string from Step 1 (CSRF verification)
{
  "sessionCode": "sess_abc123",
  "state": "random_csrf_token"
}

​
Response

​
token
string
API key with tank_ prefix (store securely)
​
user
object
User information
{
  "token": "tank_abc123def456",
  "user": {
    "name": "Jane Doe",
    "email": "[email protected]"
  }
}
Example: 
curl -X POST https://registry.tank.dev/api/v1/cli-auth/exchange \
  -H "Content-Type: application/json" \
  -d '{"sessionCode":"sess_abc123","state":"random_csrf_token"}'

​
OAuth Flow Diagram

​
Session Lifetime

  • Duration: 5 minutes
  • One-time use: Session is consumed after successful exchange
  • Storage: In-memory store (not persisted)

​
Error Responses

​
401 Unauthorized

Missing or invalid API key: 
{
  "error": "Unauthorized"
}

​
403 Forbidden

API key lacks required scope: 
{
  "error": "Insufficient API key scope. Required: skills:publish"
}
Account is suspended: 
{
  "error": "Account is suspended or banned"
}

​
400 Bad Request

Invalid session during OAuth flow: 
{
  "error": "Invalid, expired, or already used session code"
}

​
API Key Scopes

Scopes restrict what an API key can do:
ScopePermissions
skills:publishPublish new skills and versions
skills:readRead skill metadata (default for public skills)
skills:writeUpdate skill settings
skills:deleteDelete skills (requires ownership)
CLI tokens created via OAuth have skills:publish scope by default.

​
Security Best Practices

  1. Never commit API keys to version control
  2. Store keys securely in ~/.tank/config.json or environment variables
  3. Rotate keys periodically (default 90-day expiration)
  4. Use scoped keys for automation (grant minimum required permissions)
  5. Revoke compromised keys immediately via the dashboard

​
Managing API Keys

Create and manage API keys in the API Keys section:
  • View active keys
  • Create service account keys
  • Revoke keys
  • Set custom expiration and rate limits

​
Next Steps

Skills API

Publish and download skills

Search API

Search the skill registry

Build docs developers (and LLMs) love

Get started for freeTalk to us