Authentication

API Key Format

Token101 authenticates API traffic with API Keys, and the validation rules are intentionally simple. The server rejects any key that does not start with sk- or that is shorter than 32 characters in total length. That means the safest assumption for every client integration is: treat the full key as an opaque secret string, preserve the prefix, and never trim whitespace into or out of the stored value.

A valid key therefore looks like this at a high level:

• Prefix: sk-
• Minimum total length: 32 characters
• Transport: send the full key exactly as issued

Do not infer meaning from the visible prefix and do not build logic around partial key matching in client applications. Keys are credentials, not identifiers. If you need to label them operationally, use dashboard metadata or your own secret manager naming convention instead of parsing the key body.

Authentication Method

Every request to the messages endpoint must carry the key in the Authorization header using the Bearer scheme:

curl https://token.ppthub.shop/api/v1/messages \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $TOKEN101_API_KEY" \
  --data '{
    "model": "claude-sonnet-4-5-20250929",
    "max_tokens": 128,
    "messages": [
      {
        "role": "user",
        "content": "Return a one-line authentication check."
      }
    ]
  }'

Token101 also accepts the key in the x-api-key header, which the Anthropic SDK sends natively — so an SDK configured only with an API key still authenticates. The Bearer form above remains the recommended one; when both are present, the Bearer token takes precedence.

Every request must carry valid credentials. If neither header carries a valid key — the header is missing, the Authorization value does not begin with Bearer , or the key fails validation — Token101 returns 401 authentication_error before processing the request. That early failure mode is useful because it keeps auth problems clearly separated from content or billing problems.

Using with SDKs

If you are using raw HTTP only, the previous section is enough. If you are integrating in application code, configure the SDK once and keep the key in environment variables. Token101 is designed to work with the Anthropic SDK, using a custom base URL.

Python

import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["TOKEN101_API_KEY"],
    base_url="https://token.ppthub.shop/api",
)

message = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=128,
    messages=[
        {
            "role": "user",
            "content": "Return a one-line authentication check.",
        }
    ],
)

print(message.content[0].text)

JavaScript

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  apiKey: process.env.TOKEN101_API_KEY!,
  baseURL: 'https://token.ppthub.shop/api',
});

const message = await client.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 128,
  messages: [
    {
      role: 'user',
      content: 'Return a one-line authentication check.',
    },
  ],
});

console.log(message.content[0]?.text);

The base URL matters. For curl and other direct HTTP clients, use https://token.ppthub.shop/api/v1/messages. For Python and JavaScript SDK clients, set base_url or baseURL to https://token.ppthub.shop/api and let the SDK append the Claude-compatible path. Mixing those two patterns is a common source of avoidable 404s and malformed requests.

API Key Management

Create keys from the dashboard’s API Keys settings page and scope your operational process around one key per app, environment, or automation. That limits the impact if a key leaks and makes audit trails easier to understand when usage changes unexpectedly.

For rotation, use a controlled three-step flow:

1. Create a new API Key.
2. Update every deployment, worker, or CI job to use the new secret.
3. Disable or delete the old key after the cutover is confirmed.

Do not rotate by editing a secret in place without rollout tracking. The API validates the key on every request, so a stale deployment will immediately begin failing with 401 authentication_error as soon as the old key is no longer valid. Short overlap windows are acceptable; undocumented overlap windows are not.

If a key is no longer needed, revoke it by disabling or deleting it from the dashboard. Do this immediately for incident response, employee offboarding, or environment decommissioning. Revoked credentials stop working immediately with no grace period.

Security Best Practices

Treat every API Key as production-sensitive, even in development. The simplest secure baseline is:

• Store keys in environment variables or a secret manager.
• Never commit keys to Git, screenshots, tickets, or chat logs.
• Avoid sharing one key across unrelated services.
• Rotate keys after suspected exposure, not only on a fixed calendar.
• Monitor usage changes so you can detect accidental loops or leaked credentials early.

When you build local tooling, prefer TOKEN101_API_KEY in .env.local or your shell profile and keep .env* patterns in .gitignore. When you build server-side applications, inject secrets at deploy time rather than bundling them into the client. Token101 expects the key to remain server-controlled; exposing it in browser code effectively turns every visitor into your API client.

Error Handling

Most auth-related failures come back in the standard JSON envelope:

{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key"
  }
}

The most important cases to handle are:

Some 429 responses also include policy headers such as Retry-After, X-Token101-Policy-Gate, and X-Token101-Policy-Reason. Build your client so that retries are conditional, not automatic. If you retry every 401 or 403, you amplify an auth outage; if you ignore Retry-After on 429, you turn a temporary quota boundary into a self-inflicted traffic spike.

When in doubt, debug in this order: verify the full Authorization: Bearer ... header, confirm the key still exists in the dashboard, then compare the response with Quick Start, Error Handling, and Rate Limits. That sequence keeps debugging grounded in actual API behavior instead of guesswork.