Docs / API & Webhooks / API Authentication Basics

API Authentication Basics

Published · Last updated: May 2026 · 3 min read

Who this is for

Developers who want to automate CloudAIPilot operations, integrate with external tools, or build scripts that interact with the CloudAIPilot API.

What you will complete

Understand how CloudAIPilot API authentication works, obtain an API token, and make your first authenticated API request.

Before you begin

  • Owner or Admin role required to create API tokens.
  • Basic familiarity with HTTP requests and JSON.

Authentication method

CloudAIPilot uses Bearer token authentication for API access. Every API request must include a valid token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

How to obtain an API token

  1. Go to Settings in the left sidebar.
  2. Look for the API or API Tokens section.
  3. Click Generate Token or Create New Token.
  4. Give the token a descriptive name (e.g., "CI/CD pipeline token" or "Monitoring script").
  5. Copy the generated token immediately. It is shown only once and cannot be retrieved again.
  6. Store the token securely in your CI/CD secrets manager, environment variables, or password manager.

Important: Never commit API tokens to version control (git repositories). Anyone with the token has access to your organization's API.

Making an authenticated request

Example using curl:

curl -X GET "https://api.cloudaipilot.com/v1/servers" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

The API returns JSON responses.

Token scopes and permissions

API tokens inherit the permissions of the user account they are associated with. A token created by an Admin-role account has Admin-level API access.

For CI/CD pipelines that only need to trigger deployments, create the token under a Member-role account to limit potential blast radius if the token is compromised.

Token rotation and revocation

Rotate a token: Generate a new token, update all systems that use the old token, then revoke the old token.

Revoke a token: Go to Settings → API Tokens, find the token by name, and click Revoke. The token is immediately invalid. Any system using the revoked token will receive 401 Unauthorized responses.

What success looks like

  • An authenticated API request returns a 200 response with JSON data.
  • An unauthenticated request returns 401 Unauthorized.
  • A revoked token immediately returns 401 Unauthorized.

Common errors and fixes

"401 Unauthorized" Cause: Token is missing, expired, or revoked. Fix: Verify the Authorization header is formatted correctly. Check the token has not been revoked in Settings.

"403 Forbidden" Cause: The token has access to the API but the account does not have permission for this specific action. Fix: Use a token associated with a higher-privilege account (Admin or Owner) for this action.

"Token shown once — I did not copy it" Cause: API tokens are shown once for security. They cannot be retrieved after creation. Fix: Revoke the old token and generate a new one. Update all systems that used the old token.

Related articles