# Create a Vantage account

Use these endpoints to sign a person up for Vantage on their behalf and to check how far they have gotten with setup. An agent can create the account and connect cost providers such as OpenAI over HTTP, with no console steps. Connecting AWS and choosing a paid plan need the person in the console.

These endpoints are not part of the Vantage API and are not in its OpenAPI spec. Fields and status codes may change. Ignore fields you do not recognize, and re-read this page (https://console.vantage.sh/agents/accounts.md) before you integrate.

## How signup works

1. Ask the person which email address to use. Only create an account when the person has asked for one.
2. `POST https://console.vantage.sh/agents/accounts` with that email. Vantage creates the account and its owner, then emails the person a link to set a password.
3. Tell the person to open the email from Vantage and set a password when they want to sign in to the console. You can use the API before they do that.
4. Use the `api_token` from step 2 with the [Vantage API](https://docs.vantage.sh/api) to set up and query the account. To connect a cost provider such as OpenAI, Anthropic, OpenRouter, SpaceXAI, GCP, or Azure, call `POST /v2/integrations/{provider}` with credentials the person agrees to send. OpenAI needs an Admin API key (`sk-admin-...`), not a project key. See [auth.md](https://console.vantage.sh/auth.md#connect-a-cost-provider) for each credential and an example request. The person connects AWS in the Vantage console.
5. Poll `GET https://console.vantage.sh/agents/accounts/{token}` with the same token to see when they have signed in and whether they have connected a cloud provider.

Signup returns an `api_token`. It is a Vantage API token for the account owner with `read` and `write` scope. It works on every `/v2` endpoint as soon as signup returns it, including before the person sets a password, and it acts as the owner there. Other API paths return `403` for it, and some actions are only available to the person in the console. Setting a password is what lets the person sign in to the console. The token does not expire. The person sees it as "Agent signup token" under their personal API tokens in the console and can revoke it there.

New accounts start on the free Starter plan, which covers up to $2,500 of tracked cloud spend a month. No payment is needed to sign up. When an account needs a paid plan, the account status and Vantage API `402` responses include a `billing_action` that says who has to do what. See [Billing](#billing).

## Create an account

```
POST https://console.vantage.sh/agents/accounts
Content-Type: application/json

{"email": "finops@acme.com", "name": "Alex FinOps"}
```

| Field | Required | Description |
| --- | --- | --- |
| `email` | Yes | Email address for the account owner. It must not already have a Vantage account. |
| `name` | No | Display name for the owner. |
| `payment_token` | No | A Stripe Shared Payment Token (`spt_...`) that the person granted to Vantage through your platform. See [Billing](#billing). |

Vantage records the request's `User-Agent` header to report on agent signups. Send one that names your agent, such as `my-agent/1.2`.

A successful request returns `201 Created` with the account:

```json
{
  "token": "acct_ace620fc3d602740",
  "name": "finops",
  "contact_email": "finops@acme.com",
  "user_token": "usr_8dd0ac0d023cad97",
  "status": "pending_first_login",
  "onboarded": false,
  "registered": false,
  "provider_connected": false,
  "next_onboarding_step": "provider_connection",
  "plan": "Starter",
  "payment_required": false,
  "billing_action": null,
  "payment_token_on_file": false,
  "api_token": "vntg_tkn_example"
}
```

Keep `token` and `api_token`. Vantage returns `api_token` only in this response and cannot send it again. Treat it like a password: store it securely, do not log it, and do not show it to anyone but the person.

## Check account status

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

Send the `api_token` from account creation, or another account owner's personal API token, as a Bearer token in the `Authorization` header. Only account owners can read this endpoint; team tokens and tokens for users without the owner role return `403`. A missing, unknown, or revoked token returns `401`. If the person revokes the token, they can create a new one in the console after signing in at https://console.vantage.sh/login.

The response is `200 OK` with the same fields as account creation, except `api_token`. Only accounts created with `POST https://console.vantage.sh/agents/accounts` can be read here. Other accounts return `404`.

Poll no more than once a minute. Setting a password and connecting a provider take a person several minutes at least.

## Response fields

| Field | Description |
| --- | --- |
| `token` | The account token. |
| `name` | The account name. |
| `contact_email` | The account's contact email. |
| `user_token` | The token for the owner created with the account. |
| `status` | `pending_first_login`: the owner has not set a password and signed in yet. `pending_onboarding`: the owner has signed in, and onboarding is not finished. `onboarded`: onboarding is complete. |
| `onboarded` | Whether onboarding is complete. |
| `registered` | Whether the owner has completed registration in the console. |
| `provider_connected` | Whether the account has a connected cost provider. |
| `next_onboarding_step` | `provider_connection` until a cost provider is connected, then `null`. |
| `plan` | The account's plan, such as `Starter`. |
| `payment_required` | Whether cost data is blocked until a person acts on `billing_action`. |
| `billing_action` | The billing step a person must take when `payment_required` is `true`, otherwise `null`. See [Billing](#billing). |
| `payment_token_on_file` | Whether an active Shared Payment Token from signup is stored for the account. |

## Billing

When an account's tracked cloud spend goes over its plan, or its subscription lapses, `payment_required` becomes `true` and `billing_action` describes the fix. Vantage API requests that are blocked for billing return `402` with the same `billing_action` next to the usual `errors` array.

```json
{
  "type": "upgrade_plan",
  "message": "This Account's tracked cloud spend is over its Starter plan limit. An Account owner needs to choose a plan.",
  "url": "https://console.vantage.sh/settings/payment"
}
```

| `type` | What to tell the person |
| --- | --- |
| `upgrade_plan` | An account owner must choose or renew a plan at `url` while signed in. |
| `contact_account_manager` | The account is billed through the account that manages it, which must change its plan. `url` is `null`. |

Show `message` to the person. Do not retry blocked requests until they have acted.

### Shared Payment Tokens

You can pass `payment_token` when you create an account. The token must be active, in USD, allow monthly recurring charges, and set a maximum amount of at least the monthly price of the Pro plan. If the maximum is too low, the error says how much is needed. Vantage stores it for a later plan upgrade and does not charge it at signup. Signing up with a token does not change pricing: the account pays the standard price of its plan. Each token can be used for one account.

## Errors

Errors return a JSON body with an `errors` array of messages:

```json
{"errors": ["This email address can't be used to create a new Vantage account. If you already use Vantage, sign in or ask your administrator for access."]}
```

| Status | Meaning |
| --- | --- |
| `400` | `payment_token` is not a Shared Payment Token id. |
| `401` | The API token is missing, unknown, or revoked. |
| `403` | Signup is not available on this host, or the API token does not belong to an account owner. |
| `404` | No matching account, or the API token belongs to a different account. See [Check account status](#check-account-status). |
| `422` | The email is invalid or cannot be used for a new account, for example because it already has one or its company signs in with SSO. The message does not say which. Tell the person to sign in at https://console.vantage.sh/login or ask their administrator for access. Also returned when `payment_token` cannot be used; the message says why. Do not retry with the same values. |
| `429` | Too many signup requests. Wait at least an hour before you try again. |
| `503` | Signup is temporarily unavailable, or Vantage could not check `payment_token`. Try again later. |