Auth

Authenticate users and obtain access tokens.

Start email login

POST/auth/email/start

Initiates an email-based login flow by sending a verification code to the provided email address.

The response includes a nonce that must be used when verifying the login, along with timing information for the verification code.

This endpoint always returns 202 Accepted to prevent email enumeration attacks.

BodyStartEmailLoginRequestrequiredapplication/json

Request to initiate an email-based login flow. A verification code will be sent to the provided email address.

emailstringemailrequired

The email address to send the verification code to.

Responses

202

Login flow initiated. A verification code has been sent to the email address if it exists in the system.

application/json

Login flow initiated. A verification code has been sent to the email address if it exists in the system.

objectStartEmailLoginResponse

Response from initiating an email login. Contains the nonce needed for verification and timing information.

noncestringrequired

Token to reference this authentication request during verification.

expiresInintegerrequired

Number of seconds until the verification code expires.

createdAtstringdate-timerequired

When the authentication request was created.

expiresAtstringdate-timerequired

When the verification code will expire.

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the error. It is the code the failing system answered with — one of ours where the endpoint publishes one, an operator's own code where the failure came from an operator, and otherwise the request status. Prefer internalCode for branching.

internalCodestring

Names the condition that failed, from our own registry, independently of which system reported it and of the HTTP status. Stable across releases and the code to branch on in client code.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

429

Too many requests have been sent in a given amount of time.

application/json

Too many requests have been sent in a given amount of time.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the error. It is the code the failing system answered with — one of ours where the endpoint publishes one, an operator's own code where the failure came from an operator, and otherwise the request status. Prefer internalCode for branching.

internalCodestring

Names the condition that failed, from our own registry, independently of which system reported it and of the HTTP status. Stable across releases and the code to branch on in client code.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the error. It is the code the failing system answered with — one of ours where the endpoint publishes one, an operator's own code where the failure came from an operator, and otherwise the request status. Prefer internalCode for branching.

internalCodestring

Names the condition that failed, from our own registry, independently of which system reported it and of the HTTP status. Stable across releases and the code to branch on in client code.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

No auth required

POST /auth/email/start

curl https://apiv2.example.com/api/v2/auth/email/start \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "email": "john.doe@example.com"
}'

fetch('https://apiv2.example.com/api/v2/auth/email/start', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'john.doe@example.com'
  })
})

requests.post(
    "https://apiv2.example.com/api/v2/auth/email/start",
    headers={
      "Content-Type": "application/json"
    },
    json={
      "email": "john.doe@example.com"
    }
)

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/auth/email/start"

	payload := strings.NewReader(`{
  "email": "john.doe@example.com"
}`)

	req, _ := http.NewRequest("POST", requestUrl, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

202400429500

{
  "nonce": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "expiresIn": 300,
  "createdAt": "2024-01-15T10:30:00Z",
  "expiresAt": "2024-01-15T10:35:00Z"
}

{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}

{
  "message": "Too many requests. Please slow down.",
  "code": "too_many_requests",
  "hint": "Retry after the number of seconds indicated in the Retry-After header."
}

{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Verify email login

POST/auth/email/verify

Verifies an email login by validating the verification code sent to the email address.

On success, returns an OAuth2-compatible token response with:

accessToken: JWT token for authenticating subsequent API requests
tokenType: Always "Bearer"
expiresIn: Token lifetime in seconds
userId: The authenticated user's identifier

Use the access token in the Authorization header: Authorization: Bearer {accessToken}

BodyVerifyEmailLoginRequestrequiredapplication/json

Request to verify an email login by providing the verification code sent to the email address.

emailstringemailrequired

The email address used to initiate the login.

noncestringrequired

The nonce returned from the start login request.

codestringpattern ^[0-9]{6}$required

The 6-digit verification code sent to the email address.

Responses

200

Login verified successfully. Returns access token for API authentication.

application/json

Login verified successfully. Returns access token for API authentication.

objectTokenResponse

OAuth2-compatible token response containing the access token for authenticating API requests.

accessTokenstringrequired

JWT access token for authenticating API requests. Include in the Authorization header as "Bearer {accessToken}".

tokenTypeenum<string>required

The type of token issued. Always "Bearer" for JWT tokens.

values

Bearer

expiresInintegerrequired

Number of seconds until the access token expires.

userIdstring

The unique identifier of the authenticated user.

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the error. It is the code the failing system answered with — one of ours where the endpoint publishes one, an operator's own code where the failure came from an operator, and otherwise the request status. Prefer internalCode for branching.

internalCodestring

Names the condition that failed, from our own registry, independently of which system reported it and of the HTTP status. Stable across releases and the code to branch on in client code.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the error. It is the code the failing system answered with — one of ours where the endpoint publishes one, an operator's own code where the failure came from an operator, and otherwise the request status. Prefer internalCode for branching.

internalCodestring

Names the condition that failed, from our own registry, independently of which system reported it and of the HTTP status. Stable across releases and the code to branch on in client code.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

429

Too many requests have been sent in a given amount of time.

application/json

Too many requests have been sent in a given amount of time.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the error. It is the code the failing system answered with — one of ours where the endpoint publishes one, an operator's own code where the failure came from an operator, and otherwise the request status. Prefer internalCode for branching.

internalCodestring

Names the condition that failed, from our own registry, independently of which system reported it and of the HTTP status. Stable across releases and the code to branch on in client code.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the error. It is the code the failing system answered with — one of ours where the endpoint publishes one, an operator's own code where the failure came from an operator, and otherwise the request status. Prefer internalCode for branching.

internalCodestring

Names the condition that failed, from our own registry, independently of which system reported it and of the HTTP status. Stable across releases and the code to branch on in client code.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

No auth required

POST /auth/email/verify

curl https://apiv2.example.com/api/v2/auth/email/verify \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "email": "john.doe@example.com",
  "nonce": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "code": "123456"
}'

fetch('https://apiv2.example.com/api/v2/auth/email/verify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'john.doe@example.com',
    nonce: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    code: '123456'
  })
})

requests.post(
    "https://apiv2.example.com/api/v2/auth/email/verify",
    headers={
      "Content-Type": "application/json"
    },
    json={
      "email": "john.doe@example.com",
      "nonce": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "code": "123456"
    }
)

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/auth/email/verify"

	payload := strings.NewReader(`{
  "email": "john.doe@example.com",
  "nonce": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "code": "123456"
}`)

	req, _ := http.NewRequest("POST", requestUrl, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

{
  "accessToken": "<access-token>",
  "tokenType": "Bearer",
  "expiresIn": 604800,
  "userId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e"
}

{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}

{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}

{
  "message": "Too many requests. Please slow down.",
  "code": "too_many_requests",
  "hint": "Retry after the number of seconds indicated in the Retry-After header."
}

{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Auth

Start email login

Body·StartEmailLoginRequestrequiredapplication/json

Responses

Verify email login

Body·VerifyEmailLoginRequestrequiredapplication/json

Responses

BodyStartEmailLoginRequestrequiredapplication/json

BodyVerifyEmailLoginRequestrequiredapplication/json