Skip to main content
The Template Worker Public API uses OAuth2 for user authentication and supports both session-based and API token authentication.

​
Authentication Methods

The API supports two types of authentication:
  1. OAuth2 Login Sessions - For web applications and interactive use
  2. API Tokens - For programmatic access and automation

​
OAuth2 Flow

​
Creating an OAuth2 Session

To authenticate a user via Discord OAuth2, you’ll need to:
  1. Direct users to Discord’s OAuth2 authorization URL with the identify and guilds scopes
  2. Handle the OAuth2 callback with the authorization code
  3. Exchange the code for a session token
https://discord.com/api/oauth2/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_REDIRECT_URI&
  response_type=code&
  scope=identify%20guilds
Endpoint: POST /oauth2
​
code
string
required
The OAuth2 authorization code from Discord
​
redirect_uri
string
required
The redirect URI used in the OAuth2 flow. Must be in the allowed redirects list.
​
code_verifier
string
Optional PKCE code verifier for enhanced security (required for app logins)
{
  "user_id": "123456789012345678",
  "token": "long_session_token_here",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "expiry": "2026-02-28T12:00:00Z",
  "user": {
    "id": "123456789012345678",
    "username": "exampleuser",
    "global_name": "Example User",
    "avatar": "a_1234567890abcdef"
  }
}
​
user_id
string
The Discord user ID
​
token
string
The session token to use for API authentication
​
session_id
string
The unique session identifier (UUID)
​
expiry
string
ISO 8601 timestamp when the session expires
​
user
object
Partial user information (only returned on OAuth2 login)

​
Session Types

  • login: Standard web login session (1 hour expiry)
  • app_login: Application login with PKCE (14 days expiry)
  • api: API token with custom expiry

​
API Tokens

API tokens provide long-lived authentication for programmatic access.

​
Creating an API Token

You must have an existing authenticated session to create API tokens.
Create API Token
curl -X POST https://splashtail-staging.antiraid.xyz/sessions \
  -H "Authorization: YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My API Token",
    "type": "api",
    "expiry": 2592000
  }'
Endpoint: POST /sessions
​
name
string
required
A descriptive name for the API token
​
type
string
required
Must be “api” (only API tokens can be created via this endpoint)
​
expiry
integer
required
Expiry time in seconds (must be between 0 and 9223372036854775)
{
  "user_id": "123456789012345678",
  "token": "your_api_token_here",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "expiry": "2026-03-30T12:00:00Z",
  "user": null
}

​
Using Authentication

Once you have a session token or API token, include it in the Authorization header:
Authenticated Request
curl -X GET https://splashtail-staging.antiraid.xyz/sessions/@me \
  -H "Authorization: YOUR_TOKEN_HERE"

​
Get Current Session

Retrieve information about your authenticated session: Endpoint: GET /sessions/@me
Get Session Info
curl -X GET https://splashtail-staging.antiraid.xyz/sessions/@me \
  -H "Authorization: YOUR_TOKEN"

{
  "user_id": "123456789012345678",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "state": "normal",
  "type": "api"
}
​
user_id
string
The authenticated user’s Discord ID
​
id
string
The session ID
​
state
string
User state (e.g., “normal”, “banned”)
​
type
string
Session type (“login”, “app_login”, or “api”)

​
Security Notes

  • Never share your API tokens or session tokens
  • Store tokens securely and never commit them to version control
  • OAuth2 codes can only be used once - the API caches used codes for 10 minutes to prevent reuse
  • Redirect URIs must be pre-configured in the allowed redirects list
  • The identify and guilds scopes are required for OAuth2 authentication

​
Error Handling

Authentication errors return appropriate HTTP status codes:
  • 401 Unauthorized: Missing or invalid authentication token
  • 403 Forbidden: User is banned or lacks required permissions
  • 400 Bad Request: Invalid request format or parameters
{
  "message": "Invalid token specified",
  "code": "InvalidToken"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us