# auth.md

You are an agent. Vantage supports **agentic registration** for people who do not have a Vantage account yet. You can set an account up entirely over HTTP, with no console steps: create the account, get an API token, and connect cost providers such as OpenAI and Anthropic. The person sets a password from a Vantage email when they want to sign in to the console.

## At a glance

| Question | Answer |
| --- | --- |
| Can an agent create the account? | Yes. `POST https://console-staging.vantage.sh/agents/accounts` with the person's email. No payment or console step is needed. |
| When does the API token work? | As soon as registration returns it. It has `read` and `write` access to the new account. |
| Which cost providers can an agent connect? | OpenAI, Anthropic, OpenRouter, xAI, GCP, Azure, Twilio, and custom providers, with credentials the person gives you. See [Step 6](#step-6--use-the-token). |
| What needs the person in the console? | Connecting AWS, and choosing a paid plan. |
| What does it cost? | New accounts start on the free Starter plan, which covers up to $2,500 of tracked cloud spend a month. See [Billing](https://console-staging.vantage.sh/agents/accounts.md#billing). |

This file follows the structure of the [auth.md protocol](https://github.com/workos/auth.md). Vantage implements only the email-based method. It does not publish OAuth Authorization Server metadata, does not have an `/agent/identity` or `/oauth2/token` endpoint, and does not accept ID-JAGs. Do not look for them.

The registration endpoints are not part of the Vantage API, so they are not in its OpenAPI spec or API reference. The integration endpoints in Step 6 are. Re-read this file (https://console-staging.vantage.sh/auth.md) and [Create a Vantage account](https://console-staging.vantage.sh/agents/accounts.md) before you integrate.

## Step 1 — Discover

| What | Where |
| --- | --- |
| This file | https://console-staging.vantage.sh/auth.md, also served at https://console-staging.vantage.sh/.well-known/auth.md and https://console-staging.vantage.sh/agents.md |
| Agent resources index | https://console-staging.vantage.sh/llms.txt |
| Registration endpoint | `POST https://console-staging.vantage.sh/agents/accounts` |
| Registration status endpoint | `GET https://console-staging.vantage.sh/agents/accounts/{token}` |
| API the token works with | https://api.vantage.sh ([docs](https://docs.vantage.sh/api)) |
| Scopes granted | `read`, `write` |
| Bearer methods | `Authorization: Bearer` header |

## Step 2 — Pick a method

| Method | Supported | Use it when |
| --- | --- | --- |
| `service_auth` (email) | Yes | You have the person's email address and they asked for a Vantage account. |
| `identity_assertion` (ID-JAG) | No | — |
| `anonymous` | No | — |

If the person already has a Vantage account, do not register. Have them sign in at https://console-staging.vantage.sh/login and create an API token in the console, or use the [Vantage MCP server](https://docs.vantage.sh/vantage_mcp), which signs them in through OAuth.

## Step 3 — Register

Before you register, tell the person that you will create a Vantage account for their email and that you will get an API token with `read` and `write` access to it. Only continue if they agree.

```http
POST https://console-staging.vantage.sh/agents/accounts
Content-Type: application/json
User-Agent: my-agent/1.2

{"email": "finops@acme.com"}
```

Response (`201 Created`):

```json
{
  "token": "acct_ace620fc3d602740",
  "status": "pending_first_login",
  "api_token": "vntg_tkn_example"
}
```

The full response, optional fields such as `name` and `payment_token`, and every error are in [Create a Vantage account](https://console-staging.vantage.sh/agents/accounts.md).

Vantage returns `api_token` only in this response and cannot send it again. Store it securely and do not log it. You can call `/v2` with it as soon as you receive it.

## Step 4 — The person signs in

Signing in to the console requires the person to set a password. Vantage emails them a link. Opening it, setting a password, and signing in is how they get into the console. You can call the API before they do this. There is no code for you to relay.

### 4a. Hand off to the person

Suggested copy:

> I created a Vantage account for finops@acme.com. Open the email from Vantage, set a password, and sign in at https://console-staging.vantage.sh/login. Let me know when you're done.

### 4b. Poll for completion

```http
GET https://console-staging.vantage.sh/agents/accounts/acct_ace620fc3d602740
Authorization: Bearer vntg_tkn_example
```

| `status` | Meaning |
| --- | --- |
| `pending_first_login` | The person has not set a password and signed in yet. The API token already works. |
| `pending_onboarding` | The person has signed in, and onboarding is not finished. |
| `onboarded` | The person has signed in, and onboarding is complete. |

Poll when you need to know whether the person has signed in or connected a provider. Poll no more than once a minute, and stop after a day without progress. If the person cannot find the email from Vantage, ask them to check their spam folder.

## Step 5 — Exchange

There is nothing to exchange. The `api_token` from Step 3 is the access token. It does not expire, and there is no refresh token.

## Step 6 — Use the token

```http
GET https://api.vantage.sh/v2/me
Authorization: Bearer vntg_tkn_example
```

The token acts as the account owner on `/v2` endpoints. Other API paths return `403` for it, and some actions are only available to the person in the console.

### Connect a cost provider

Connect a provider with `POST https://api.vantage.sh/v2/integrations/{provider}` for `open_ai`, `anthropic`, `openrouter`, `xai`, `gcp`, `azure`, `twilio`, or `custom_provider`. OpenAI and Anthropic each have a second integration type: send `codex_analytics: true` to `open_ai` for OpenAI Codex Analytics, or `enterprise_analytics: true` to `anthropic` for Claude Enterprise Analytics. See the [Integrations API](https://docs.vantage.sh/api) for each body. AWS can only be connected by the person in the console.

Before you send a provider credential, tell the person which credential you will send to Vantage and only continue if they agree. Vantage uses it to read cost and usage data from the provider. The credential may already be on the person's machine, for example in an environment variable such as `OPENAI_ADMIN_KEY`; check for it without printing its value. Do not log it or show it.

| Provider | `{provider}` | Credential |
| --- | --- | --- |
| OpenAI | `open_ai` | An OpenAI Admin API key, which starts with `sk-admin-`. Only an OpenAI organization owner can create one. Project keys do not work. |
| Anthropic | `anthropic` | An Anthropic Admin API key. Regular API keys do not work. |

```http
POST https://api.vantage.sh/v2/integrations/open_ai
Authorization: Bearer vntg_tkn_example
Content-Type: application/json

{"api_key": "sk-admin-...", "description": "OpenAI production"}
```

The integration starts as `pending`, and the account's `provider_connected` becomes `true`. Check import progress with `GET https://api.vantage.sh/v2/integrations/{token}`, using the `token` from the response. `status` moves to `importing` and then `imported` once costs are available, or to `error` if Vantage cannot read the provider's cost data. Importing can take a while. Poll no more than once every few minutes.

If the account needs a paid plan, API requests return `402` with a `billing_action`. Show its `message` to the person. See [Billing](https://console-staging.vantage.sh/agents/accounts.md#billing).

## Errors

| Status | Where | What to do |
| --- | --- | --- |
| `401` | status endpoint, Vantage API | The token is missing, unknown, or revoked. See [Revocation](#revocation). |
| `403` | Vantage API, not `/v2` | The token only works on `/v2` endpoints. Use the `/v2` equivalent, or ask the person to do it in the console. |
| `403` | `/v2/integrations/{provider}` | That integration type is not available for this account. Ask the person to connect it in the console. |
| `403` | status endpoint | The token does not belong to an account owner. Use the token from Step 3. |
| `403` | registration endpoint | Registration is not available on this host. Do not retry. |
| `422` | registration endpoint | The email is invalid or cannot be used for a new account. Do not retry; send the person to https://console-staging.vantage.sh/login. |
| `429` | registration endpoint | Wait at least an hour before you try again. |
| `503` | registration endpoint | Registration is temporarily unavailable. Retry later with exponential backoff. |

Do not retry a `4xx` with the same request.

## Revocation

The person can revoke the token in the console, where it is listed under their personal API tokens as "Agent signup token". Vantage has no endpoint for you to revoke it. After revocation, every request returns `401`. Do not register again: the account still exists. Ask the person to sign in at https://console-staging.vantage.sh/login and give you a new API token.