Authentication

How to authenticate with the Skytells API — API keys, request format, and error handling.

All requests to the Skytells API must be authenticated using an API key passed in the x-api-key header. This is the only supported authentication method.

An API key is a unique, secret token that authenticates your identity when communicating with the Skytells API. Every interaction — whether through the REST API, an official SDK, or the Console — requires a valid API key linked to your account.

Your API key serves two purposes:

Identification — Tells the platform which account is making the request, so usage and billing are attributed correctly.
Authorization — Determines what resources you can access based on your account's plan and permissions.

Creating a New API Key

To create a new API key, follow the steps below. Please refer to the API Keys page for more information.

Authenticating Requests

Include the x-api-key header in every API call:

curl https://api.skytells.ai/v1/models \
  -H "x-api-key: $SKYTELLS_API_KEY"

import Skytells from 'skytells';

const client = Skytells(process.env.SKYTELLS_API_KEY);
const models = await client.models.list();

API Key Security

Never share your API key publicly, commit it to version control, or embed it in client-side code.

Do	Don't
Store keys in environment variables or a secrets manager	Hard-code keys in source files
Use separate keys per environment	Reuse one key everywhere
Rotate keys on a regular schedule	Keep the same key indefinitely
Revoke keys you're no longer using	Leave old, unused keys active
Keep keys server-side only	Expose keys in frontend / client-side code

Error Handling

When a request fails authentication, the API returns a 401 error:

{
  "error": {
    "http_status": 401,
    "message": "Invalid or missing API key",
    "details": "Please obtain a valid API key from the dashboard",
    "error_id": "UNAUTHORIZED"
  }
}

Error Types

Error ID	HTTP Status	Meaning
`UNAUTHORIZED`	401	The API key is invalid, expired, or missing.
`INVALID_REQUEST`	422	The request is malformed or missing required fields.
`NOT_FOUND`	404	The requested resource does not exist.

Rate Limiting

API requests are subject to rate limits. If you exceed the limit, you'll receive a 429 Too Many Requests response. For headers, retry strategies, and best practices, see Rate Limits.

How is this guide?

Authentication

On this page