Docs

REST API

The Alien REST API lets your backend manage projects, customers, setup links, releases, and deployments over HTTPS. Use it when your product needs to drive Alien directly, for example to create a setup link when a customer clicks Deploy or to show deployment status on a settings page.

curl "https://api.alien.dev/v1/deployments?project=acme&limit=20" \
  -H "Authorization: Bearer $ALIEN_API_KEY"

For TypeScript, use the typed platform API client. The endpoint pages in this section are generated from the OpenAPI document at /openapi.json.

Base URL

https://api.alien.dev

All endpoints are under /v1. Requests and responses are JSON.

Authentication

Send an API key as a Bearer token:

Authorization: Bearer ax_...

Create keys under Settings → API Keys in the dashboard, or with alien api-keys create. Every key belongs to one workspace, so you don't need to pass the workspace query parameter. If you send it, it must match the key's workspace.

Keep keys in server-side secret storage. Never send one to a browser.

Scopes and roles

A key has one scope, and a role within that scope. Pick the narrowest one that does the job.

ScopeRolesTypical use
workspaceworkspace.viewer, workspace.member, workspace.adminAutomation across every project in a workspace.
projectproject.viewer, project.developer, project.adminYour backend or CI: create setup links, publish releases, read deployments.
project (services)project.encryption, project.ai-gateway, project.sandbox-gateway, project.remote-bindingsA hosted app that calls the Customer-managed keys API, the AI Gateway, Remote Sandboxes, or remote bindings.
deploymentdeployment.viewer, deployment.manager, deployment.dynamic-container-manager, deployment.telemetry-writerAccess to one deployment, such as sending it commands.
deployment-groupdeployment-group.deployerThe token inside a setup link. It can only set up deployments for that customer.

OAuth 2.0

Interactive clients, including alien login, use the OAuth 2.0 authorization code flow with PKCE (https://api.alien.dev/auth/oauth2/authorize and /auth/oauth2/token). Requests made with a user token must name the workspace with ?workspace=<name> or the x-alien-workspace header.

Customers and external IDs

A customer is a deployment group. Each group can carry an external ID: your own tenant ID, case-sensitive, up to 128 characters of letters, digits, ., _, ~, and -. Use it to look customers up without storing Alien IDs:

TaskEndpoint
Create a setup link for a tenant (creates the group if needed)POST /v1/deployment-groups/setup-links
Get or create the group for a tenantPUT /v1/deployment-groups/by-external-id
Find the group for a tenantGET /v1/deployment-groups/by-external-id
List that customer's deploymentsGET /v1/deployments?deploymentGroup=<id>

The hosted AI Gateway and the Customer-managed keys API use the same external ID in the X-Alien-External-ID header to pick the customer's models or key.

Pagination

List endpoints take limit (1 to 100, default 20) and cursor, and return:

{
  "items": [],
  "nextCursor": "eyJpZCI6ImRlcF8..."
}

Pass nextCursor as cursor to get the next page. nextCursor is null on the last page.

Errors

Errors return a 4xx or 5xx status and a JSON body:

{
  "code": "NOT_FOUND",
  "message": "Deployment dep_123 not found",
  "retryable": false,
  "internal": false,
  "hint": null,
  "requestId": "req_..."
}
FieldMeaning
codeStable, machine-readable error type. Branch on this, not on message.
messageHuman-readable description.
retryabletrue when the same request may succeed later. Retry with backoff.
internaltrue for server-side errors. The message then contains no details.
hintOptional next step.
contextOptional structured details, such as validation errors.
requestIdInclude it when you contact support.

Endpoint groups

The sidebar lists every endpoint group. Most integrations use these:

Next

On this page