Authentication

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

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

{
  "kind": "goodVerifySent",
  "message": "The account verification email was sent."
}

{
  "kind": "goodRegisterV2",
  "message": "The user was created.",
  "data": {
    "authToken": "<auth-token>",
    "teamToken": "<team-token>"
  }
}

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

{
  "kind": "badCtftimeToken",
  "message": "The CTFtime token provided is invalid."
}

{
  "kind": "badEmail",
  "message": "The email address is malformed."
}

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

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

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

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

{
  "kind": "badRegistrationsDisabled",
  "message": "The registrations are disabled."
}

{
  "kind": "badCaptcha",
  "message": "The captcha verification failed."
}

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

{
  "kind": "badJson",
  "message": "The request JSON body is malformed."
}

{
  "kind": "badBody",
  "message": "The request body does not meet requirements.",
  "data": {
    "reason": "<reason>"
  }
}

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

{
  "kind": "goodVerifySent",
  "message": "The account verification email was sent."
}

{
  "kind": "goodRegister",
  "message": "The user was created.",
  "data": {
    "authToken": "<auth-token>"
  }
}

{
  "kind": "badCtftimeToken",
  "message": "The CTFtime token provided is invalid."
}

{
  "kind": "badEmail",
  "message": "The email address is malformed."
}

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

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

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

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

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

{
  "kind": "badRegistrationsDisabled",
  "message": "The registrations are disabled."
}

{
  "kind": "badRecaptchaCode",
  "message": "The recaptcha code is invalid."
}

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

{
  "kind": "badJson",
  "message": "The request JSON body is malformed."
}

{
  "kind": "badBody",
  "message": "The request body does not meet requirements.",
  "data": {
    "reason": "<reason>"
  }
}

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

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.

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
*
 required

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

Auth token returned by the route.

teamTokenstring

Team token returned by the route.

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
*
 required

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

Auth token returned by the route.

Email registrations are checked against division ACLs before the verification email is sent. The server chooses the default allowed division for the email address, so the client does not send a division in this request. CTFtime registrations do not go through email ACLs.

`POST` Verify a token

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

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

{
  "kind": "goodVerify",
  "message": "The email was verified.",
  "data": {
    "authToken": "<auth-token>"
  }
}

{
  "kind": "goodEmailSet",
  "message": "The email was successfully updated."
}

{
  "kind": "goodRegisterV2",
  "message": "The user was created.",
  "data": {
    "authToken": "<auth-token>",
    "teamToken": "<team-token>"
  }
}

{
  "kind": "badTokenVerification",
  "message": "The token provided is invalid."
}

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

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

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

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

{
  "kind": "badUnknownUser",
  "message": "The user does not exist."
}

{
  "kind": "badJson",
  "message": "The request JSON body is malformed."
}

{
  "kind": "badBody",
  "message": "The request body does not meet requirements.",
  "data": {
    "reason": "<reason>"
  }
}

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

{
  "kind": "goodVerify",
  "message": "The email was verified.",
  "data": {
    "authToken": "<auth-token>"
  }
}

{
  "kind": "goodEmailSet",
  "message": "The email was successfully updated."
}

{
  "kind": "goodRegister",
  "message": "The user was created.",
  "data": {
    "authToken": "<auth-token>"
  }
}

{
  "kind": "badTokenVerification",
  "message": "The token provided is invalid."
}

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

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

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

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

{
  "kind": "badUnknownUser",
  "message": "The user does not exist."
}

{
  "kind": "badJson",
  "message": "The request JSON body is malformed."
}

{
  "kind": "badBody",
  "message": "The request body does not meet requirements.",
  "data": {
    "reason": "<reason>"
  }
}

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
*
 required

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

Auth token returned by the route.

teamTokenstring

Team token returned by the route.

Response fields

authTokenstring

Auth token returned by the route.

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

Auth token returned by the route.

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

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

{
  "kind": "goodVerifySent",
  "message": "The account verification email was sent."
}

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

{
  "kind": "badEmail",
  "message": "The email address is malformed."
}

{
  "kind": "badUnknownEmail",
  "message": "The account does not exist."
}

{
  "kind": "badCaptcha",
  "message": "The captcha verification failed."
}

{
  "kind": "badJson",
  "message": "The request JSON body is malformed."
}

{
  "kind": "badBody",
  "message": "The request body does not meet requirements.",
  "data": {
    "reason": "<reason>"
  }
}

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

{
  "kind": "goodVerifySent",
  "message": "The account verification email was sent."
}

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

{
  "kind": "badEmail",
  "message": "The email address is malformed."
}

{
  "kind": "badUnknownEmail",
  "message": "The account does not exist."
}

{
  "kind": "badRecaptchaCode",
  "message": "The recaptcha code is invalid."
}

{
  "kind": "badJson",
  "message": "The request JSON body is malformed."
}

{
  "kind": "badBody",
  "message": "The request body does not meet requirements.",
  "data": {
    "reason": "<reason>"
  }
}

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

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. Unknown emails still get the same 200 goodVerifySent envelope, which keeps the recovery endpoint from becoming an account lookup tool.

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

Request body

email
*
 required

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
*
 required

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.

If email delivery is not configured, recovery cannot be started because there is nowhere to send the token. Captcha and email validation are handled before any recovery email is queued.

`GET` Preview a verification token

GET /api/v2/auth/verify-info

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

{
  "kind": "goodVerifyInfo",
  "message": "The verification info was retrieved.",
  "data": {
    "kind": "register",
    "email": "team@example.com",
    "name": "otter-sec"
  }
}

{
  "kind": "badTokenVerification",
  "message": "The token provided is invalid."
}

{
  "kind": "badBody",
  "message": "The request body does not meet requirements.",
  "data": {
    "reason": "<reason>"
  }
}

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
*
 required

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"

Response or object kind.

emailstring | null

Email address.

namestring | undefined

Display name.

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

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

{
  "kind": "goodLogin",
  "message": "The login was successful.",
  "data": {
    "authToken": "<auth-token>"
  }
}

{
  "kind": "badUnknownUser",
  "message": "The user does not exist."
}

{
  "kind": "badTokenVerification",
  "message": "The token provided is invalid."
}

{
  "kind": "badCtftimeToken",
  "message": "The CTFtime token provided is invalid."
}

{
  "kind": "badJson",
  "message": "The request JSON body is malformed."
}

{
  "kind": "badBody",
  "message": "The request body does not meet requirements.",
  "data": {
    "reason": "<reason>"
  }
}

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.

Request body

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.

Response#

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.

Response fields

authTokenstring

Auth token returned by the route.

`GET` Test an auth token

GET /api/v1/auth/test

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

{
  "kind": "goodToken",
  "message": "The authorization token is valid."
}

{
  "kind": "badToken",
  "message": "The token provided is invalid."
}

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.