Getting Started

Authentication

The RaceHooks API authenticates with OAuth 2.0 client credentials: you exchange a client_id and client_secret for a short-lived Bearer token. Before you can get those credentials you need a verified account. This page walks the full path — sign up, verify your email, get your credentials, and mint a token — and serves as the reference for every /v1/auth endpoint.

The flow at a glance
  1. Sign up — POST /v1/auth/signup
  2. Verify your email — POST /v1/auth/verify-email (also logs you in)
  3. Get your credentials — console API Keys page, or POST /v1/oauth/credentials
  4. Exchange them for a Bearer token — POST /v1/oauth
1

Sign up

Create an account. Email, password, and the three consent flags are required.

FieldTypeDescription
emailstringYour email address. A verification link is sent here.
passwordstring8–72 characters.
tosAcceptedbooleanMust be true — accepts the Terms of Service.
privacyAcceptedbooleanMust be true — accepts the Privacy Policy.
aupAcceptedbooleanMust be true — accepts the Acceptable Use Policy.
namestring?Optional display name.
bash
curl -X POST https://api.racehooks.io/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "your-strong-password",
    "tosAccepted": true,
    "privacyAccepted": true,
    "aupAccepted": true
  }'

# Response
{
  "data": {
    "message": "Account created. Check your email to verify and access your credentials."
  }
}
ℹ
If the verification email can't be sent, signup returns 502 with code email_delivery_failed — your account is still created, so retry with POST /v1/auth/resend-verification rather than signing up again.
2

Verify your email

Verification is mandatory — you cannot log in or reach your credentials until it's done. The email contains a link to racehooks.io/verify-email?token=…; opening it verifies you. There are two API calls, and the distinction matters:

FieldTypeDescription
GET /v1/auth/verify-email?token=read-onlyChecks whether a token is valid. Does NOT verify the account — safe for email scanners to prefetch.
POST /v1/auth/verify-emailcommitConsumes the token, activates the account, and sets a session cookie. This is the one that verifies you.
bash
# The email links to https://racehooks.io/verify-email?token=<token>.
# That page confirms verification for you. To do it programmatically:

# 1. (Optional) Check a token is still valid — read-only, does NOT verify:
curl "https://api.racehooks.io/v1/auth/verify-email?token=<token>"
# → { "data": { "valid": true } }

# 2. Commit verification — activates the account and sets a session cookie:
curl -X POST https://api.racehooks.io/v1/auth/verify-email \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{ "token": "<token>" }'
# → { "data": { "success": true } }   (Set-Cookie: session=…)
✦
Lost or expired link? POST /v1/auth/resend-verification with your email sends a fresh one (and invalidates older links). It always returns 200so it can't be used to probe which emails have accounts.
3

Get your credentials

Your client_id and client_secret are created with your account. Grab them from the API Keys page in the console, or fetch them programmatically with the session cookie set by verify-email (or login):

bash
# Using the session cookie from verify-email (or POST /v1/auth/login),
# fetch your credentials — no browser needed:
curl -X POST https://api.racehooks.io/v1/oauth/credentials \
  -b cookies.txt

# Response
{
  "data": {
    "clientId": "rh_your_client_id",
    "clientSecret": "your_client_secret"
  }
}
⚠
Treat the client_secretlike a password. It's retrievable while your session is valid; if it leaks, rotate it with POST /v1/console/regenerate-secret (which also invalidates any live Bearer tokens).
4

Exchange credentials for a Bearer token

Post your credentials to /v1/oauth. The returned token is valid for 12 hours; include it as an Authorization: Bearer header on every protected request.

bash
curl -X POST https://api.racehooks.io/v1/oauth \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "rh_your_client_id",
    "client_secret": "your_client_secret",
    "grant_type": "client_credentials"
  }'

# Response
{
  "access_token": "…",
  "token_type": "Bearer",
  "expires_in": 43200
}

# Use it on every protected request:
#   Authorization: Bearer <access_token>

Logging in (session auth)

POST /v1/auth/login authenticates an existing, verified account with email and password and sets a session cookie. It is the entry point for the console and for POST /v1/oauth/credentials — it does not return a Bearer token. Use the client-credentials exchange above for API tokens.

bash
curl -X POST https://api.racehooks.io/v1/auth/login \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{ "email": "you@example.com", "password": "your-strong-password" }'

# Response — sets a session cookie (NOT a Bearer token)
{
  "data": { "clientId": "rh_...", "name": null, "email": "you@example.com" }
}

Before verification, login returns 403 "Please verify your email before signing in". POST /v1/auth/logout clears the session.

Endpoint reference

FieldTypeDescription
POST /v1/auth/signuppublicCreate an account and send a verification email.
POST /v1/auth/verify-emailpublicConsume a token, verify the account, set a session cookie.
GET /v1/auth/verify-emailpublicRead-only token validity check (no side effects).
POST /v1/auth/resend-verificationpublicResend the verification email for an unverified account.
POST /v1/auth/loginpublicEmail + password → session cookie.
POST /v1/auth/logoutsessionClear the current session.
POST /v1/oauth/credentialssessionReturn { clientId, clientSecret } for the logged-in account.
POST /v1/oauthpublicExchange client_id + client_secret for a Bearer token.

Rate limits

The auth endpoints are rate-limited per IP: signup 5/10 min, login 10/5 min, resend-verification 3/10 min. When you exceed a limit the response is 429 with code rate_limit_exceeded and a Retry-After header (seconds) — back off for that long before retrying.

← QuickstartWebhooks & delivery →