# Quick start

Anything you can do in the Portal web UI (managing tenants, buckets, access keys, compute instances, and more) you can automate through the Aurora Portal REST API.

## When to use the Portal API

- **CI/CD pipelines** — create buckets, rotate access keys, or provision compute as part of automated workflows
- **Infrastructure-as-code** — script repeatable environment setup alongside your deployments
- **Custom tooling** — build internal dashboards, monitoring integrations, or management CLIs on top of Aurora
- **Bulk operations** — automate tasks that would be tedious through the UI

## Base URL

All API requests are made against:

```
https://api-portal.aur.lu/api
```

## Create an API token

Tokens are created in the Aurora Dashboard, or through the API itself using an existing token.

**In the Portal:**

1. Log in to the [Aurora Portal](https://portal.aur.lu/)
2. Navigate to **Credentials → API Tokens**
3. Click **New Token**
4. Enter a name, optional description, and optional expiration date, and select the permissions the token should have
5. Click **Create** and copy the token immediately

**Through the API**, with an existing token — useful for rotating credentials from a pipeline:

```bash
curl -X POST \
  -H "X-Api-Key: atp_YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ci-deploy",
    "description": "CI pipeline token",
    "expiresAt": "2027-01-31",
    "permissions": ["read:s3:buckets", "create:s3:buckets", "read:s3:access_keys"]
  }' \
  https://api-portal.aur.lu/api/auth/v2/tenants/YOUR_TENANT_ID/tokens
```

`permissions` is required and lists what the new token may do, in the form `<action>:<component>:<resource>` (for example `read:compute:instances` or `execute:inference:requests`). A token can only grant permissions that the calling token itself holds; requesting more returns `403`. The full list of accepted values is in the [Create token v2](https://docs.aur.lu/docs/portal-api/reference/create-token-v-2) reference.

`description` and `expiresAt` are optional; `expiresAt` takes a `YYYY-MM-DD` date and the token expires at the end of that day (UTC). The response includes the new token value in the `token` field.

> **Warning**
>
> The token value is shown **only once** at creation. Store it securely—you cannot retrieve it later.

Tokens are scoped to a single tenant. Each token has a prefix (`atp_`) followed by a random string. You can create multiple tokens per tenant, each with its own name and expiration.

## Authenticate with X-Api-Key

Pass your token in the `X-Api-Key` header on every request. Requests with a body must set `Content-Type: application/json`.

```bash
curl -H "X-Api-Key: atp_YOUR_TOKEN_HERE" \
  https://api-portal.aur.lu/api/v1/tenants
```

> **Note**
>
> The `X-Api-Key` header is the only supported authentication method for programmatic access. Do not use `Authorization: Bearer` with API tokens—that flow is reserved for browser sessions.

## Permissions

Every endpoint requires one permission, shown at the top of its page in the [API Reference](https://docs.aur.lu/docs/portal-api/reference/aurora-portal-api) right under the route (for example `read:s3:buckets` for listing buckets). A token can call an endpoint only if it holds that permission.

Permissions are named `<action>:<component>:<resource>`:

- **action** — `read`, `create`, `update`, `delete`, or a resource-specific verb such as `operate` (start/stop instances), `clone`, `restore`, or `execute`
- **component** — `s3`, `compute`, `inference`, or `portal` (tenants, tags, tokens)
- **resource** — the object the action applies to, such as `buckets`, `instances`, or `tokens`

Calling an endpoint with a token that lacks the permission returns `403` with the message `Missing permission <name>`. Grant the missing permission by creating a new token with it; permissions of an existing token cannot be changed. The full list of values is in the [Create token v2](https://docs.aur.lu/docs/portal-api/reference/create-token-v-2) reference.

## Try it out

List your tenants:

```bash
curl -s -H "X-Api-Key: atp_YOUR_TOKEN_HERE" \
  https://api-portal.aur.lu/api/v1/tenants | jq
```

List VM instances for a tenant:

```bash
curl -s -H "X-Api-Key: atp_YOUR_TOKEN_HERE" \
  https://api-portal.aur.lu/api/compute/v1/tenants/YOUR_TENANT_ID/instances | jq
```

List S3 buckets for a tenant:

```bash
curl -s -H "X-Api-Key: atp_YOUR_TOKEN_HERE" \
  https://api-portal.aur.lu/api/v1/tenants/YOUR_TENANT_ID/buckets | jq
```

## Token lifecycle

- **Expiration** — tokens can optionally expire on a set date. Expired tokens are rejected automatically.
- **Deletion** — delete tokens at any time from the Portal under Credentials → API Tokens, or via `DELETE /auth/v1/tenants/:tenantId/tokens/:tokenId`.
- **Scope** — each token is bound to one tenant and cannot access resources of other tenants. Within the tenant, it can only perform the actions covered by its permissions.
- **Rotation** — create a new token, update your integrations, then delete the old one.

## Next steps

- [Responses & Errors](https://docs.aur.lu/docs/portal-api/portal-api-responses) — understand the response format, status codes, and pagination
- [OpenAPI Specification](https://docs.aur.lu/docs/portal-api/portal-api-openapi-spec) — download the raw spec for client generation or LLM use
- [API Reference](https://docs.aur.lu/docs/portal-api/reference/aurora-portal-api) — browse the full interactive API documentation