Authentication
Create an account and get an API key without a browser: register_account returns a live key instantly; the emailed-code flow (device_login_start + device_login_complete) signs an existing account in and mints a new key.
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), 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.
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
| 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. |
Responses
- 201
Account created. Store
default_project.api_keys.livenow: it is never shown again. - 400
invalid_json: the body is not valid JSON.validation_error: email missing or malformed, or password shorter than 8 characters.disposable_email: the email domain is a disposable-mail provider. - 409
email_taken: an account with this email (or the same Gmail inbox under another spelling) already exists. Usedevice_login_startto sign in and get a key. - 429
rate_limit_exceeded: more than 5/v1/auth/*requests per minute from this IP. HonourRetry-After.
curl -X POST https://api.pixelvault.dev/v1/auth/register \
-H "Content-Type: application/json" \
-d '{
"email": "dev@example.com",
"password": "your-secure-password"
}' {
"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. Finish with 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
| 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: the body is not valid JSON.validation_error: email missing or malformed.disposable_email: the email domain is a disposable-mail provider. - 409
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: a code was sent to this account in the last 60 seconds.rate_limit_exceeded: more than 5/v1/auth/*requests per minute from this IP. - 500
server_error: the account could not be created; retry.
curl -X POST https://api.pixelvault.dev/v1/auth/device/start \
-H "Content-Type: application/json" \
-d '{"email":"dev@example.com"}' {
"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 / 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
| 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 |
replace_existing | boolean | Optional | Delete older secret keys with the same label after minting this one. |
Responses
- 200
Signed in. The key is shown only once.
- 400
invalid_json: the body is not valid JSON.validation_error: email or code missing.code_expired: no code was requested or it is older than 10 minutes.too_many_attempts: 3 wrong guesses; request a new code.invalid_code: wrong code, or already used. - 404
not_found: no account for this email; calldevice_login_startfirst. - 429
rate_limit_exceeded: more than 5/v1/auth/*requests per minute from this IP. - 500
server_error: the account has no project.
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
}' {
"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
}
}