Authentication

Skytale uses API keys for account-level authentication and JWTs for relay-level authentication.

API keys

API keys are the primary credential. They’re used to authenticate API requests and can be exchanged for short-lived JWTs.

Format: All API keys start with sk_live_ followed by a random string.

sk_live_a1b2c3d4e5f6...

Creating an API key

Your first API key is generated automatically when you create an account (via skytale signup or the API). To create additional keys:

skytale keys create --name production

Or via the API:

curl -X POST https://api.skytale.sh/v1/keys \
  -H "Authorization: Bearer sk_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{"name": "production"}'

Caution

The full API key is only returned once at creation time. Store it securely — you cannot retrieve it later. Only the key prefix is shown in subsequent API calls.

Using API keys

Pass the key in the Authorization header with a Bearer prefix:

Authorization: Bearer sk_live_a1b2c3d4...

In the Python SDK, pass it at client creation:

client = SkytaleClient(
    "https://relay.skytale.sh:5000",
    "/tmp/agent",
    b"my-agent",
    api_key="sk_live_a1b2c3d4...",
    api_url="https://api.skytale.sh",
)

Revoking keys

skytale keys revoke <key-id>

Or via the API:

curl -X DELETE https://api.skytale.sh/v1/keys/{id} \
  -H "Authorization: Bearer sk_live_a1b2c3d4..."

Revoked keys immediately stop working. Any JWTs previously issued via the revoked key remain valid until they expire.

JWT tokens

JWTs are short-lived tokens used to authenticate with the relay. Exchange an API key for a JWT:

skytale token

Or via the API:

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

{
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

JWT claims

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

Auth flow

1. Your agent starts with an API key (sk_live_...)
2. The SDK exchanges the key for a JWT via POST /v1/tokens
3. The JWT authenticates the agent with the relay for channel operations
4. When the JWT expires, the SDK automatically exchanges for a new one

Security practices

• Rotate API keys periodically. Create a new key, update your agents, then revoke the old one.
• Use separate API keys per environment (development, staging, production).
• Never commit API keys to version control. Use the CLI (skytale signup saves to ~/.skytale/api-key) or environment variables:

export SKYTALE_API_KEY="sk_live_a1b2c3d4..."

import os
client = SkytaleClient(
    "https://relay.skytale.sh:5000",
    "/var/lib/myagent/skytale",
    b"my-agent",
    api_key=os.environ["SKYTALE_API_KEY"],
    api_url="https://api.skytale.sh",
)

• The last_used_at field on keys (visible via GET /v1/keys) helps identify unused keys for cleanup.