Getting Started

Authentication

The Twin.Actor API supports two authentication methods: JWT Bearer tokens for user-facing applications and API keys for server-to-server integrations.

Authentication Methods

JWT Bearer Token

Best for web and mobile applications where users log in with their credentials. Tokens expire after 7 days.

http

Authorization</span>: Bearer eyJhbGciOiJIUzI1NiIs...

API Key (Coming Soon)

Best for server-to-server integrations and automated systems. Keys can be scoped and rotated.

http

X-API-Key</span>: sk_live_abc123...

API key authentication is coming soon. Currently, use JWT tokens for all integrations.

Getting a Token

Register a New Account

POST/auth/register

Create a new user account

Request Body

Name	Type	Description
`email`required	`string`	Valid email address
`password`required	`string`	Minimum 8 characters
`name`	`string`	Display name

bash

curl -X POST https://api.twin.actor/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "developer@example.com",
    "password": "secure_password_123",
    "name": "Jane Developer"
  }'

Response:

json

{
  "user": {
    "id": "usr_abc123",
    "email": "developer@example.com",
    "name": "Jane Developer",
    "credits": 1000,
    "is_verified": false
  },
  "token": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "bearer"
  },
  "message": "Registration successful! Check your email to verify your account."
}

201Account created successfully

400Invalid email or password format

409Email already registered

Login

POST/auth/login

Authenticate with email and password

OAuth2 Form Format

The login endpoint uses OAuth2 form encoding, not JSON. Use application/x-www-form-urlencoded content type.

Request Body (Form)

Name	Type	Description
`username`required	`string`	Your email address
`password`required	`string`	Your password

bash

curl -X POST https://api.twin.actor/api/v1/auth/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=developer@example.com&password=secure_password_123"

Response:

json

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3JfYWJjMTIzIiwiZW1haWwiOiJkZXZlbG9wZXJAZXhhbXBsZS5jb20iLCJleHAiOjE3MTEwMDAwMDB9.signature",
  "token_type": "bearer"
}

200Login successful

401Invalid credentials

Using Your Token

Include the token in the Authorization header of every request:

http

GET</span> /api/v1/persons HTTP/1.1
Host</span>: api.twin.actor
Authorization</span>: Bearer eyJhbGciOiJIUzI1NiIs...

bash

curl https://api.twin.actor/api/v1/persons \
  -H "Authorization: Bearer YOUR_TOKEN"

Token Expiration

JWT tokens expire after 7 days. When a token expires, you'll receive a 401 error:

json

{
  "detail": "Token has expired"
}

To continue using the API, simply log in again to get a new token. We recommend:

Store the token expiration time when you receive it
Refresh the token before it expires (e.g., after 6 days)
Handle 401 errors gracefully by re-authenticating

Decoding Token Expiration

JWT tokens contain their expiration time in the payload. You can decode it (without verification) to check when it expires:

python

"text-violet-400">import base64
"text-violet-400">import json

# Get the payload (second part of the token)
payload = token.split(".")[1]
# Add padding "text-violet-400">and decode
payload += "=" * (4 - len(payload) % 4)
data = json.loads(base64.b64decode(payload))
expires_at = data["exp"]  # Unix timestamp

Get Current User

GET/auth/me

Get the currently authenticated user's profile

bash

curl https://api.twin.actor/api/v1/auth/me \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

json

{
  "id": 1,
  "email": "developer@example.com",
  "name": "Jane Developer",
  "credits": 8500,
  "is_verified": true,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-03-20T14:45:00Z"
}

Check Credits

GET/auth/credits

Get current credit balance and pricing information

bash

curl https://api.twin.actor/api/v1/auth/credits \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

json

{
  "credits": 8500,
  "credits_per_second_video": 10,
  "credits_per_photo": 100
}

Email Verification

New accounts must verify their email address. A verification link is sent during registration.

Verify Email

POST/auth/verify-email

Verify email with token from verification link

bash

curl -X POST "https://api.twin.actor/api/v1/auth/verify-email?token=VERIFICATION_TOKEN"

Resend Verification

POST/auth/resend-verification

Request a new verification email

bash

curl -X POST https://api.twin.actor/api/v1/auth/resend-verification \
  -H "Authorization: Bearer YOUR_TOKEN"

Password Management

Change Password

POST/auth/change-password

Change password for the current user

Request Body

Name	Type	Description
`current_password`required	`string`	Current password
`new_password`required	`string`	New password (min 8 characters)

bash

curl -X POST https://api.twin.actor/api/v1/auth/change-password \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "current_password": "old_password",
    "new_password": "new_secure_password"
  }'

Error Responses

Authentication errors return these status codes:

401Missing or invalid authentication token

401Token has expired

403Valid token but insufficient permissions

Example error response:

json

{
  "detail": "Could not validate credentials"
}

Best Practices

Never expose tokens in client-side code - Use a backend proxy for browser applications
Use environment variables - Store tokens in TWIN_ACTOR_TOKEN or similar
Handle expiration gracefully - Implement automatic re-authentication when tokens expire
Use HTTPS only - Never send tokens over unencrypted connections
Rotate tokens regularly - Re-authenticate periodically for long-running services