Tokens

Exchange token

Exchange an API key (or existing JWT) for a new short-lived JWT. The JWT is used to authenticate with the relay for channel operations.

POST /v1/tokens

Authentication: Required (API key preferred).

CLI

skytale token

curl

curl -X POST https://api.skytale.sh/v1/tokens \
  -H "Authorization: Bearer sk_live_a1b2c3d4..."

Response 200

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

JWT claims

The returned JWT contains these claims:

Claim	Type	Description
sub	string	Account UUID
iss	string	Issuer (always skytale-api)
plan	string	Plan tier (free, dev, team, enterprise)
exp	number	Expiration timestamp (Unix seconds)
iat	number	Issued-at timestamp (Unix seconds)

Usage

The JWT authenticates your agent with the relay. The Python SDK handles token exchange automatically when you provide an api_key and api_url:

# The SDK exchanges the API key for a JWT internally
client = SkytaleClient(
    "https://relay.skytale.sh:5000",
    "/tmp/agent",
    b"my-agent",
    api_key="sk_live_a1b2c3d4...",
    api_url="https://api.skytale.sh",
)

If you’re building a custom integration, exchange the key for a JWT and pass the JWT to the relay:

import requests

resp = requests.post(
    "https://api.skytale.sh/v1/tokens",
    headers={"Authorization": "Bearer sk_live_a1b2c3d4..."},
)
jwt = resp.json()["token"]
# Use jwt for relay authentication

Errors

Status	Error	Cause
401	missing authorization header	No auth header provided
401	invalid or revoked api key	API key not found or revoked