Authentication API reference

Sign-in helpers for the CLI and AI agents. Backend applications use an API key from the dashboard.

Requests go to https://api.revdoku.com. Every path starts with /v1, for example https://api.revdoku.com/v1/buckets. Send Authorization: Bearer $REVDOKU_API_KEY from your server. Tables use JSON names; where TypeScript differs, a field shows json_name / typescriptName. Python uses the JSON names.

Operations that need no API key run before you have one. They use the generated DefaultApi class instead of Revdoku, so their errors are ResponseError (TypeScript) or ApiException (Python), not RevdokuError.

All operations · API guide · Errors · OpenAPI

• Email a sign-in code: POST /v1/auth/sign_in_code
• Exchange a sign-in code for an API key: POST /v1/auth/sign_in_code/verify
• Exchange a one-time dashboard connection code for an API key: POST /v1/auth/grant/exchange
• Create a dashboard link: POST /v1/auth/dashboard_link

Email a sign-in code

POST /v1/auth/sign_in_code

Needs no API key.

Sends a six-digit code to an existing account email. The response is the same for every address, so it never reveals whether an account exists. Create new accounts in the browser at https://app.revdoku.com/users/sign_up.

Request body: TypeScript requestSignInCodeRequest: RequestSignInCodeRequest, Python request_sign_in_code_request=RequestSignInCodeRequest(...).

Examples

TypeScript

import { DefaultApi } from 'revdoku';

// This operation needs no API key, so it uses the generated API class.
const api = new DefaultApi();
const { data } = await api.requestSignInCode({
  requestSignInCodeRequest: { email: 'you@example.com' },
});
console.log(data);

Python

from revdoku import DefaultApi, RequestSignInCodeRequest

# This operation needs no API key, so it uses the generated API class.
api = DefaultApi()
response = api.request_sign_in_code(
    RequestSignInCodeRequest(email="you@example.com"),
)
print(response.data)

cURL

curl -X POST "https://api.revdoku.com/v1/auth/sign_in_code" \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

Response 200

Errors

Guide: Authentication

Exchange a sign-in code for an API key

POST /v1/auth/sign_in_code/verify

Needs no API key.

Creates an AI agent connection for an account owner or administrator. Accounts with two-factor authentication must use browser sign-in.

Request body: TypeScript verifySignInCodeRequest: VerifySignInCodeRequest, Python verify_sign_in_code_request=VerifySignInCodeRequest(...).

Examples

TypeScript

import { DefaultApi } from 'revdoku';

// This operation needs no API key, so it uses the generated API class.
const api = new DefaultApi();
const { data } = await api.verifySignInCode({
  verifySignInCodeRequest: { email: 'you@example.com', code: '123456' },
});
console.log(data);

Python

from revdoku import DefaultApi, VerifySignInCodeRequest

# This operation needs no API key, so it uses the generated API class.
api = DefaultApi()
response = api.verify_sign_in_code(
    VerifySignInCodeRequest(email="you@example.com", code="123456"),
)
print(response.data)

cURL

curl -X POST "https://api.revdoku.com/v1/auth/sign_in_code/verify" \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "code": "123456"}'

Response 201

Errors

Guide: Authentication

Exchange a one-time dashboard connection code for an API key

POST /v1/auth/grant/exchange

Needs no API key.

The dashboard creates the one-time code when a signed-in administrator copies a connection prompt.

Request body: TypeScript exchangeConnectionGrantRequest: ExchangeConnectionGrantRequest, Python exchange_connection_grant_request=ExchangeConnectionGrantRequest(...).

Examples

TypeScript

import { DefaultApi } from 'revdoku';

// This operation needs no API key, so it uses the generated API class.
const api = new DefaultApi();
const { data } = await api.exchangeConnectionGrant({
  exchangeConnectionGrantRequest: { grantToken: 'ONE_TIME_CODE' },
});
console.log(data);

Python

from revdoku import DefaultApi, ExchangeConnectionGrantRequest

# This operation needs no API key, so it uses the generated API class.
api = DefaultApi()
response = api.exchange_connection_grant(
    ExchangeConnectionGrantRequest(grant_token="ONE_TIME_CODE"),
)
print(response.data)

cURL

curl -X POST "https://api.revdoku.com/v1/auth/grant/exchange" \
  -H "Content-Type: application/json" \
  -d '{"grant_token": "ONE_TIME_CODE"}'

Response 201

Errors

Guide: Authentication

Create a dashboard link

POST /v1/auth/dashboard_link

Returns a dashboard URL for a path such as /buckets. The user signs in normally; the link grants no access.

Request body: TypeScript createDashboardLinkRequest: CreateDashboardLinkRequest, Python create_dashboard_link_request=CreateDashboardLinkRequest(...).

Examples

TypeScript

import { Revdoku } from 'revdoku';

const client = new Revdoku();
const { data } = await client.api.createDashboardLink({
  createDashboardLinkRequest: { redirectPath: '/buckets' },
});
console.log(data);

Python

from revdoku import Revdoku, CreateDashboardLinkRequest

client = Revdoku()
response = client.api.create_dashboard_link(
    CreateDashboardLinkRequest(redirect_path="/buckets"),
)
print(response.data)

cURL

curl -X POST "https://api.revdoku.com/v1/auth/dashboard_link" \
  -H "Authorization: Bearer $REVDOKU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"redirect_path": "/buckets"}'

Response 201

Errors

Guide: Authentication