<!-- Markdown twin of https://pixelvault.dev/docs/api/authentication/ -->

[API reference](/docs/api/)

# Authentication

Create an account and get an API key without a browser: [`register_account`](/docs/api/authentication/#register_account) returns a live key instantly; the emailed-code flow ([`device_login_start`](/docs/api/authentication/#device_login_start) + [`device_login_complete`](/docs/api/authentication/#device_login_complete)) signs an existing account in and mints a new key.

-   POST [Create account and get API key](#register_account)
-   POST [Start email-code sign-in](#device_login_start)
-   POST [Exchange the emailed code for an API key](#device_login_complete)

## Create account and get API key

POST `/v1/auth/register`

Creates an account with a default project and returns a live secret API key (`pv_live_`) instantly. No browser or signup form needed.

The password is optional: omit it for a passwordless (agent) account; the owner can set one later through the password-reset flow to enable dashboard login. Keys are hashed server-side, so the raw key is shown only in this response.

The account starts unverified and a verification email is sent. Until the email is verified the account can store at most 5 images ([`email_verification_required`](/docs/errors/#email_verification_required)), and video, audio, generation and editing are unavailable. Free-plan limits apply: 200 MB storage, 500 uploads a month, 1 GB bandwidth a month; see [pricing](https://pixelvault.dev/pricing/).

Emails are lowercased; disposable email domains are refused. All `/v1/auth/*` endpoints share a limit of 5 requests per minute per IP.

### Authentication

None. This endpoint is public.

### Request body

`application/json`, required

Request body

Name

Type

Required

Description

`email`

string (email)

Required

An address you can receive the verification email at.

`password`

string

Optional

Optional. Omit for a passwordless account; provide (min 8 chars) to enable password login immediately.

min length 8

### Responses

-   201
    
    Account created. Store `default_project.api_keys.live` now: it is never shown again.
    
-   400
    
    [`invalid_json`](/docs/errors/#invalid_json): the body is not valid JSON. [`validation_error`](/docs/errors/#validation_error): email missing or malformed, or password shorter than 8 characters. [`disposable_email`](/docs/errors/#disposable_email): the email domain is a disposable-mail provider.
    
-   409
    
    [`email_taken`](/docs/errors/#email_taken): an account with this email (or the same Gmail inbox under another spelling) already exists. Use [`device_login_start`](/docs/api/authentication/#device_login_start) to sign in and get a key.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 5 `/v1/auth/*` requests per minute from this IP. Honour `Retry-After`.
    

Request

curlNode.jsPythonCLI

```
curl -X POST https://api.pixelvault.dev/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
  "email": "dev@example.com",
  "password": "your-secure-password"
}'
```

Response 201

```
{
  "data": {
    "account_id": "acct_abc123",
    "email": "dev@example.com",
    "email_verified": false,
    "password_set": false,
    "plan": "free",
    "default_project": {
      "id": "proj_xyz789",
      "name": "Default",
      "api_keys": {
        "live": "pv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

## Start email-code sign-in

POST `/v1/auth/device/start`

Step 1 of a passwordless sign-in that needs no browser, for tools and agents that have an account but no key. Emails a 6-digit code (valid 10 minutes) to the address; creates the account first if the email is new, exactly like [`register_account`](/docs/api/authentication/#register_account). Finish with [`device_login_complete`](/docs/api/authentication/#device_login_complete).

At most one code per 60 seconds per account; disposable email domains are rejected. Needs a person (or a mailbox the caller controls) to read the code. All `/v1/auth/*` endpoints share a limit of 5 requests per minute per IP.

### Authentication

None. This endpoint is public.

### Request body

`application/json`, required

Request body

Name

Type

Required

Description

`email`

string (email)

Required

The account email; a new address creates a passwordless account.

### Responses

-   200
    
    Code sent
    
-   400
    
    [`invalid_json`](/docs/errors/#invalid_json): the body is not valid JSON. [`validation_error`](/docs/errors/#validation_error): email missing or malformed. [`disposable_email`](/docs/errors/#disposable_email): the email domain is a disposable-mail provider.
    
-   409
    
    [`email_taken`](/docs/errors/#email_taken): the address is another spelling of an existing account's Gmail inbox; sign in with the address that was registered.
    
-   429
    
    [`rate_limited`](/docs/errors/#rate_limited): a code was sent to this account in the last 60 seconds. [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 5 `/v1/auth/*` requests per minute from this IP.
    
-   500
    
    [`server_error`](/docs/errors/#server_error): the account could not be created; retry.
    

Request

curlNode.jsPython

```
curl -X POST https://api.pixelvault.dev/v1/auth/device/start \
  -H "Content-Type: application/json" \
  -d '{"email":"dev@example.com"}'
```

Response 200

```
{
  "data": {
    "sent": true
  }
}
```

## Exchange the emailed code for an API key

POST `/v1/auth/device/complete`

Step 2 of the email-code sign-in. Validates the code (3 attempts, single use), marks the email verified, and returns a **new** live secret API key for the account's default project. The key is shown once.

Each call mints an additional key (default label `PixelVault Desktop`; list and revoke them with [`list_keys`](/docs/api/api-keys/#list_keys) / [`revoke_key`](/docs/api/api-keys/#revoke_key)), unless `replace_existing` is true, which deletes the older secret keys that share the same `label` so reconnecting does not pile them up.

### Authentication

None. This endpoint is public.

### Request body

`application/json`, required

Request body

Name

Type

Required

Description

`email`

string (email)

Required

`code`

string

Required

The 6-digit code from the email.

`label`

string

Optional

Name for the new key, trimmed and cut to 40 characters. Shown in the dashboard and in [`list_keys`](/docs/api/api-keys/#list_keys).

Default: `PixelVault Desktop`

max length 40

`replace_existing`

boolean

Optional

Delete older secret keys with the same label after minting this one.

Default: `false`

### Responses

-   200
    
    Signed in. The key is shown only once.
    
-   400
    
    [`invalid_json`](/docs/errors/#invalid_json): the body is not valid JSON. [`validation_error`](/docs/errors/#validation_error): email or code missing. [`code_expired`](/docs/errors/#code_expired): no code was requested or it is older than 10 minutes. [`too_many_attempts`](/docs/errors/#too_many_attempts): 3 wrong guesses; request a new code. [`invalid_code`](/docs/errors/#invalid_code): wrong code, or already used.
    
-   404
    
    [`not_found`](/docs/errors/#not_found): no account for this email; call [`device_login_start`](/docs/api/authentication/#device_login_start) first.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 5 `/v1/auth/*` requests per minute from this IP.
    
-   500
    
    [`server_error`](/docs/errors/#server_error): the account has no project.
    

Request

curlNode.jsPython

```
curl -X POST https://api.pixelvault.dev/v1/auth/device/complete \
  -H "Content-Type: application/json" \
  -d '{
  "email": "dev@example.com",
  "code": "123456",
  "label": "my-agent",
  "replace_existing": true
}'
```

Response 200

```
{
  "data": {
    "account_id": "acct_abc123",
    "key_id": "key_abc123",
    "api_key": "pv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "project_id": "proj_xyz789",
    "email": "dev@example.com",
    "email_verified": true
  }
}
```
