Authentication

Registration, verification, recovery, login, and token validation routes.

Last updated Jul 15, 2026

Route	Endpoint
Register a team	`POST /api/[v2,v1]/auth/register`
Verify a token	`POST /api/[v2,v1]/auth/verify`
Recover an account	`POST /api/[v2,v1]/auth/recover`
Preview a verification token	`GET /api/v2/auth/verify-info`
Log in	`POST /api/v1/auth/login`
Test an auth token	`GET /api/v1/auth/test`

Authentication in rCTF is based around teams. A team owns the name, email address, score, solves, members, and settings. Browser sessions and API clients act on behalf of a team by sending an auth token in the Authorization header.

The API has both V1 and V2 routes. They are available together, and a client may need routes from both versions. V2 routes exist where behavior changed or new response data was added. V1 routes remain current when there is no V2 replacement.

Most authenticated API requests use the Authorization: Bearer <auth-token> header.

The other token kinds are used while setting up, recovering, or changing a team account.

Token kind	Lifetime	Used by
`Auth`	No expiry	`Authorization: Bearer <auth-token>` on user routes.
`Team`	No expiry	Account recovery, login, and token verification.
`Verify`	`loginTimeout`	Email updates and pending registrations. Single use.
`CtftimeAuth`	`loginTimeout`	CTFtime registration and login handoff.

Tokens are encrypted with AES 256 GCM using tokenKey. Rotating tokenKey invalidates any auth, team, verify, or CTFtime handoff token issued before the rotation.

Verify tokens also depend on a one time Redis marker. The encrypted token can still decrypt successfully after the marker has been used or expired, but the verification request will not complete.

Note (Version choice)

For new clients, prefer the V2 route when both V1 and V2 exist for the same action. V2 uses the newer captcha field name and returns more response data. V1 remains useful for actions that do not have a V2 route, such as logging in with a team token or testing an auth token.

`POST` Register a team

POST /api/[v2,v1]/auth/register

Edit this page View Markdown

Last updated Jul 15, 2026

curl -sS "https://rctf.osec.io/api/v2/auth/register" \
  --json '{
    "email": "team@example.com",
    "name": "otter-sec",
    "captchaCode": "<captcha-code>"
  }'

1
{
2
  "kind": "goodVerifySent",
3
  "message": "The account verification email was sent."
4
}

1
{
2
  "kind": "goodRegisterV2",
3
  "message": "The user was created.",
4
  "data": {
5
    "authToken": "<auth-token>",
6
    "teamToken": "<team-token>"
7
  }
8
}

1
{
2
  "kind": "badCompetitionNotAllowed",
3
  "message": "You are not allowed to join this CTF."
4
}

1
{
2
  "kind": "badCtftimeToken",
3
  "message": "The CTFtime token provided is invalid."
4
}

1
{
2
  "kind": "badEmail",
3
  "message": "The email address is malformed."
4
}

1
{
2
  "kind": "badKnownCtftimeId",
3
  "message": "An account with this CTFtime ID already exists."
4
}

1
{
2
  "kind": "badName",
3
  "message": "The name should only use english letters, numbers, and symbols."
4
}

1
{
2
  "kind": "badKnownName",
3
  "message": "An account with this name already exists."
4
}

1
{
2
  "kind": "badKnownEmail",
3
  "message": "An account with this email already exists."
4
}

1
{
2
  "kind": "badRegistrationsDisabled",
3
  "message": "The registrations are disabled."
4
}

1
{
2
  "kind": "badCaptcha",
3
  "message": "The captcha verification failed."
4
}

1
{
2
  "kind": "badEndpoint",
3
  "message": "The request endpoint could not be found."
4
}

1
{
2
  "kind": "badRateLimit",
3
  "message": "You are trying this too fast.",
4
  "data": {
5
    "timeLeft": 600000
6
  }
7
}

1
{
2
  "kind": "badJson",
3
  "message": "The request JSON body is malformed."
4
}

1
{
2
  "kind": "badBody",
3
  "message": "The request body does not meet requirements.",
4
  "data": {
5
    "reason": "name: Required"
6
  }
7
}

curl -sS "https://rctf.osec.io/api/v1/auth/register" \
  --json '{
    "email": "team@example.com",
    "name": "otter-sec",
    "recaptchaCode": "<recaptcha-code>"
  }'

1
{
2
  "kind": "goodVerifySent",
3
  "message": "The account verification email was sent."
4
}

1
{
2
  "kind": "goodRegister",
3
  "message": "The user was created.",
4
  "data": {
5
    "authToken": "<auth-token>"
6
  }
7
}

1
{
2
  "kind": "badCtftimeToken",
3
  "message": "The CTFtime token provided is invalid."
4
}

1
{
2
  "kind": "badEmail",
3
  "message": "The email address is malformed."
4
}

1
{
2
  "kind": "badName",
3
  "message": "The name should only use english letters, numbers, and symbols."
4
}

1
{
2
  "kind": "badCompetitionNotAllowed",
3
  "message": "You are not allowed to join this CTF."
4
}

1
{
2
  "kind": "badKnownCtftimeId",
3
  "message": "An account with this CTFtime ID already exists."
4
}

1
{
2
  "kind": "badKnownEmail",
3
  "message": "An account with this email already exists."
4
}

1
{
2
  "kind": "badKnownName",
3
  "message": "An account with this name already exists."
4
}

1
{
2
  "kind": "badRegistrationsDisabled",
3
  "message": "The registrations are disabled."
4
}

1
{
2
  "kind": "badRecaptchaCode",
3
  "message": "The recaptcha code is invalid."
4
}

1
{
2
  "kind": "badEndpoint",
3
  "message": "The request endpoint could not be found."
4
}

1
{
2
  "kind": "badRateLimit",
3
  "message": "You are trying this too fast.",
4
  "data": {
5
    "timeLeft": 600000
6
  }
7
}

1
{
2
  "kind": "badJson",
3
  "message": "The request JSON body is malformed."
4
}

1
{
2
  "kind": "badBody",
3
  "message": "The request body does not meet requirements.",
4
  "data": {
5
    "reason": "name: Required"
6
  }
7
}

Auth: Public
Gate: None
Permissions: No extra permissions
Captcha: register
Rate limit: Verification email buckets. Burst 20, refill window 600000 ms per IP, plus burst 2, refill window 3600000 ms per email. Only consumed when a verification email would be sent.

Creates a team account. Most deployments ask the team to prove ownership of an email address before the account becomes usable, so a successful request often sends a verification email instead of returning tokens immediately.

For new clients, prefer the V2 route. The V1 route remains available for clients that already use the original registration fields.

The verification email limits apply even when captcha is enabled. They are consumed only when rCTF would send an email, so immediate registrations and CTFtime registrations do not count against them. Exceeding either limit returns 429 badRateLimit with the wait in data.timeLeft.

POST /api/v2/auth/register uses captchaCode for captcha protected registration. If the team can be created immediately, the response includes both an auth token for user routes and a team token for recovery or team scoped auth flows.

Request body

emailstring: Required when ctftimeToken is omitted.
name*string: 2-64 printable ASCII characters.
ctftimeTokenstring: Required when email is omitted. Only usable when CTFtime auth is configured.
captchaCodestring: Checked only when captcha protects register.

Response

If email verification is enabled, the route returns 200 goodVerifySent. The team is not created yet. Submit the verification token to verify a token to finish registration.

If no verification step is needed, the route creates the team immediately and returns 200 goodRegisterV2 with both tokens.

Response fields

authTokenstring: Bearer token authenticating the new session.
teamTokenstring: Token used to invite teammates to the team.

POST /api/v1/auth/register uses recaptchaCode for captcha protected registration. If the team can be created immediately, the response includes an auth token.

Request body

emailstring: Required when ctftimeToken is omitted.
name*string: 2-64 printable ASCII characters.
ctftimeTokenstring: Required when email is omitted. Only usable when CTFtime auth is configured.
recaptchaCodestring: Checked only when captcha protects register.

Response

If email verification is enabled, the route returns 200 goodVerifySent. The team is not created yet. Submit the verification token to verify a token to finish registration.

If no verification step is needed, the route creates the team immediately and returns 200 goodRegister with an authToken.

Response fields

authTokenstring: Bearer token authenticating the new session.

For email registration, rCTF checks division ACLs before sending the verification message and chooses the default division allowed for that address. The client does not send a division. CTFtime registration bypasses email ACLs.

`POST` Verify a token

POST /api/[v2,v1]/auth/verify

Edit this page View Markdown

Last updated Jul 15, 2026

curl -sS "https://rctf.osec.io/api/v2/auth/verify" \
  --json '{
    "verifyToken": "<verify-token>"
  }'

1
{
2
  "kind": "goodVerify",
3
  "message": "The email was verified.",
4
  "data": {
5
    "authToken": "<auth-token>"
6
  }
7
}

1
{
2
  "kind": "goodEmailSet",
3
  "message": "The email was successfully updated."
4
}

1
{
2
  "kind": "goodRegisterV2",
3
  "message": "The user was created.",
4
  "data": {
5
    "authToken": "<auth-token>",
6
    "teamToken": "<team-token>"
7
  }
8
}

1
{
2
  "kind": "badTokenVerification",
3
  "message": "The token provided is invalid."
4
}

1
{
2
  "kind": "badEmailChangeDivision",
3
  "message": "You are not allowed to stay in your division with this email."
4
}

1
{
2
  "kind": "badKnownCtftimeId",
3
  "message": "An account with this CTFtime ID already exists."
4
}

1
{
2
  "kind": "badKnownEmail",
3
  "message": "An account with this email already exists."
4
}

1
{
2
  "kind": "badKnownName",
3
  "message": "An account with this name already exists."
4
}

1
{
2
  "kind": "badUnknownUser",
3
  "message": "The user does not exist."
4
}

1
{
2
  "kind": "badJson",
3
  "message": "The request JSON body is malformed."
4
}

1
{
2
  "kind": "badBody",
3
  "message": "The request body does not meet requirements.",
4
  "data": {
5
    "reason": "name: Required"
6
  }
7
}

curl -sS "https://rctf.osec.io/api/v1/auth/verify" \
  --json '{
    "verifyToken": "<verify-token>"
  }'

1
{
2
  "kind": "goodVerify",
3
  "message": "The email was verified.",
4
  "data": {
5
    "authToken": "<auth-token>"
6
  }
7
}

1
{
2
  "kind": "goodEmailSet",
3
  "message": "The email was successfully updated."
4
}

1
{
2
  "kind": "goodRegister",
3
  "message": "The user was created.",
4
  "data": {
5
    "authToken": "<auth-token>"
6
  }
7
}

1
{
2
  "kind": "badTokenVerification",
3
  "message": "The token provided is invalid."
4
}

1
{
2
  "kind": "badEmailChangeDivision",
3
  "message": "You are not allowed to stay in your division with this email."
4
}

1
{
2
  "kind": "badKnownCtftimeId",
3
  "message": "An account with this CTFtime ID already exists."
4
}

1
{
2
  "kind": "badKnownEmail",
3
  "message": "An account with this email already exists."
4
}

1
{
2
  "kind": "badKnownName",
3
  "message": "An account with this name already exists."
4
}

1
{
2
  "kind": "badUnknownUser",
3
  "message": "The user does not exist."
4
}

1
{
2
  "kind": "badJson",
3
  "message": "The request JSON body is malformed."
4
}

1
{
2
  "kind": "badBody",
3
  "message": "The request body does not meet requirements.",
4
  "data": {
5
    "reason": "name: Required"
6
  }
7
}

Auth: Public
Gate: None
Permissions: No extra permissions
Captcha: No captcha
Rate limit: No rate limit

Checks a verification style token and applies the related account change. The same endpoint handles pending registrations, account recovery with a team token, and email change confirmations.

For new clients, prefer the V2 route. It returns more registration data when a pending registration is completed.

Request body

verifyToken*string: Pending-registration, team, or verify token.

POST /api/v2/auth/verify can complete a pending registration, return an auth token from a team token, or confirm an email change.

Response

Token kind	Success kind	Effect
Pending registration	`200 goodRegisterV2`	Creates the team, returns both tokens, and marks the verification row as used.
Team	`200 goodVerify`	Returns a fresh `authToken`.
Verify	`200 goodEmailSet`	Updates the team email after checking division ACLs again.

For pending registrations, the response body matches the immediate success response from register a team. Team tokens are recovery or login credentials, so the response returns a fresh authToken. Email change tokens do not return data after the email is updated.

Response fields

authTokenstring: Bearer token authenticating the new session.
teamTokenstring: Token used to invite teammates to the team.

Response fields

authTokenstring: Bearer token authenticating the verified session.

POST /api/v1/auth/verify can complete a pending registration, return an auth token from a team token, or confirm an email change.

Response

Token kind	Success kind	Effect
Pending registration	`200 goodRegister`	Creates the team, returns `authToken`, and marks the verification row as used.
Team	`200 goodVerify`	Returns a fresh `authToken`.
Verify	`200 goodEmailSet`	Updates the team email after checking division ACLs again.

Pending registration and team token flows both return a fresh auth token. Email change tokens do not return data after the email is updated.

Response fields

authTokenstring: Bearer token authenticating the new session.

Verification can fail even when the token decrypts correctly. Verify tokens can be used once and expire after loginTimeout. Email change tokens also check division ACLs and duplicate email constraints when the request is submitted.

`POST` Recover an account

POST /api/[v2,v1]/auth/recover

Edit this page View Markdown

Last updated Jul 15, 2026

curl -sS "https://rctf.osec.io/api/v2/auth/recover" \
  --json '{
    "email": "<email>",
    "captchaCode": "<captcha-code>"
  }'

1
{
2
  "kind": "goodVerifySent",
3
  "message": "The account verification email was sent."
4
}

1
{
2
  "kind": "badEndpoint",
3
  "message": "The request endpoint could not be found."
4
}

1
{
2
  "kind": "badEmail",
3
  "message": "The email address is malformed."
4
}

1
{
2
  "kind": "badUnknownEmail",
3
  "message": "The account does not exist."
4
}

1
{
2
  "kind": "badCaptcha",
3
  "message": "The captcha verification failed."
4
}

1
{
2
  "kind": "badRateLimit",
3
  "message": "You are trying this too fast.",
4
  "data": {
5
    "timeLeft": 600000
6
  }
7
}

1
{
2
  "kind": "badJson",
3
  "message": "The request JSON body is malformed."
4
}

1
{
2
  "kind": "badBody",
3
  "message": "The request body does not meet requirements.",
4
  "data": {
5
    "reason": "name: Required"
6
  }
7
}

curl -sS "https://rctf.osec.io/api/v1/auth/recover" \
  --json '{
    "email": "<email>",
    "recaptchaCode": "<recaptcha-code>"
  }'

1
{
2
  "kind": "goodVerifySent",
3
  "message": "The account verification email was sent."
4
}

1
{
2
  "kind": "badEndpoint",
3
  "message": "The request endpoint could not be found."
4
}

1
{
2
  "kind": "badEmail",
3
  "message": "The email address is malformed."
4
}

1
{
2
  "kind": "badUnknownEmail",
3
  "message": "The account does not exist."
4
}

1
{
2
  "kind": "badRecaptchaCode",
3
  "message": "The recaptcha code is invalid."
4
}

1
{
2
  "kind": "badRateLimit",
3
  "message": "You are trying this too fast.",
4
  "data": {
5
    "timeLeft": 600000
6
  }
7
}

1
{
2
  "kind": "badJson",
3
  "message": "The request JSON body is malformed."
4
}

1
{
2
  "kind": "badBody",
3
  "message": "The request body does not meet requirements.",
4
  "data": {
5
    "reason": "name: Required"
6
  }
7
}

Auth: Public
Gate: None
Permissions: No extra permissions
Captcha: recover
Rate limit: Recovery email buckets. Burst 5, refill window 1500000 ms per IP, plus burst 2, refill window 3600000 ms per email.

Starts account recovery for a team that still has access to its email inbox. When the request is accepted, the server sends a recovery email containing a team token.

The response does not reveal whether the email belongs to an account. Known and unknown addresses both return 200 goodVerifySent.

The recovery limits apply even when captcha is enabled. rCTF checks them before looking up the account, so rate-limit behavior cannot reveal whether an address is registered. Exceeding either limit returns 429 badRateLimit with the wait in data.timeLeft.

POST /api/v2/auth/recover uses captchaCode for captcha protected recovery.

Request body

email*string: Recovery destination.
captchaCodestring: Checked only when captcha protects recover.

Response

When email delivery is configured and the request passes validation, the route returns 200 goodVerifySent. Submit the recovery token from the email to verify a token to mint a fresh auth token.

POST /api/v1/auth/recover uses recaptchaCode for captcha protected recovery.

Request body

email*string: Recovery destination.
recaptchaCodestring: Checked only when captcha protects recover.

Response

When email delivery is configured and the request passes validation, the route returns 200 goodVerifySent. The recovery token from the email can be exchanged for an auth token with log in or submitted to verify a token.

Recovery requires an email provider. rCTF validates the request, captcha, and rate limits before queuing the message.

`GET` Preview a verification token

GET /api/v2/auth/verify-info

Edit this page View Markdown

Last updated Jul 15, 2026

curl -sS "https://rctf.osec.io/api/v2/auth/verify-info?token=<token>"

1
{
2
  "kind": "goodVerifyInfo",
3
  "message": "The verification info was retrieved.",
4
  "data": {
5
    "kind": "register",
6
    "email": "team@example.com",
7
    "name": "otter-sec"
8
  }
9
}

1
{
2
  "kind": "badTokenVerification",
3
  "message": "The token provided is invalid."
4
}

1
{
2
  "kind": "badBody",
3
  "message": "The request body does not meet requirements.",
4
  "data": {
5
    "reason": "name: Required"
6
  }
7
}

Auth: Public
Gate: None
Permissions: No extra permissions
Captcha: No captcha
Rate limit: No rate limit

Reads the public context for a verification token without marking it as used. This is useful before rendering a confirmation page, because the UI can show what the token is about before the user submits it.

This preview step is available in V2. V1 clients submit the token directly when the user confirms the action.

Query parameters

token*string: Pending-registration, team, or verify token.

Response

A valid token returns 200 goodVerifyInfo with enough detail to describe the pending action.

Response fields

kind"register" | "team" | "update": What completing this verification will do.
emailstring | null: Email tied to the verification, or null when absent.
namestring | undefined: Team name tied to the verification, when present.

Previewing does not mark the token as used. The same token still has to be submitted to verify a token to complete the action.

`POST` Log in

POST /api/v1/auth/login

Edit this page View Markdown

Last updated Jul 15, 2026

curl -sS "https://rctf.osec.io/api/v1/auth/login" \
  --json '{
    "teamToken": "<team-token>"
  }'

Auth: Public
Gate: None
Permissions: No extra permissions
Captcha: No captcha
Rate limit: No rate limit

Exchanges a longer lived team credential for an auth token that can be used on user routes. This V1 route is still current because there is no V2 replacement for team token login.

teamTokenstring: Required when ctftimeToken is omitted.
ctftimeTokenstring: Required when teamToken is omitted.

teamToken is parsed as TokenKind.Team. ctftimeToken is parsed as TokenKind.CtftimeAuth and then matched to a team linked to that CTFtime ID.

A successful login returns 200 goodLogin with a fresh authToken. Token verification happens before any account data is returned, so expired, malformed, or unrecognized handoff tokens never mint an auth token.

authTokenstring: Bearer token authenticating the session.

`GET` Test an auth token

GET /api/v1/auth/test

Edit this page View Markdown

Last updated Jul 15, 2026

curl -sS "https://rctf.osec.io/api/v1/auth/test" \
  -H "Authorization: Bearer <auth-token>"

1
{
2
  "kind": "goodToken",
3
  "message": "The authorization token is valid."
4
}

1
{
2
  "kind": "badToken",
3
  "message": "The token provided is invalid."
4
}

Auth: Required
Gate: None
Permissions: No extra permissions
Captcha: No captcha
Rate limit: No rate limit

Checks whether the current auth token is still usable. This V1 route is still current because there is no V2 replacement for token validation.

A valid token returns 200 goodToken with no data. Missing, malformed, expired, or otherwise invalid auth headers are rejected before any account data is returned.