Skip to content

Authentication

OpenSkip uses two authentication methods: JWT tokens for interactive sessions and API keys for programmatic access.

Public vs Protected Endpoints

Action Authentication Required
Reading shows, episodes, timestamps :material-close: No
Submitting timestamps :material-check: Yes
Managing your account :material-check: Yes
Admin operations :material-check: Yes (Admin role)

Registration

Invite Code Required

Registration requires a valid invite code. Contact an administrator to obtain one.

POST /api/v1/auth/register 
{
  "username": "myusername",
  "email": "user@example.com",
  "password": "securepassword123",
  "invite_code": "INVITE_CODE_HERE"
}

Response: 

{
  "id": 1,
  "username": "myusername",
  "email": "user@example.com",
  "role": "contributor",
  "is_active": true,
  "is_approved": false,
  "created_at": "2024-01-15T10:30:00Z"
}

Approval Required

New accounts require admin approval before you can log in. You'll receive a "pending approval" message until approved.

JWT Authentication

Login

POST /api/v1/auth/token 
{
  "username": "myusername",
  "password": "securepassword123"
}

Response: 

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer"
}

Using the Token

Include the token in the Authorization header:

curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  https://api.openskip.io/api/v1/auth/me

Token Expiration

JWT tokens expire after 24 hours. Request a new token by logging in again.

API Key Authentication

API keys are ideal for automated scripts and integrations.

Create an API Key

Requires JWT authentication first.

POST /api/v1/auth/api-keys 
{
  "name": "My Plex Plugin",
  "permissions": "submit"
}

Permissions:

Permission Access Level
read Read-only access
submit Can submit timestamps
moderate Can review submissions (moderators only)

Response: 

{
  "id": 1,
  "key_prefix": "osk_abc1",
  "name": "My Plex Plugin",
  "permissions": "submit",
  "is_active": true,
  "created_at": "2024-01-15T10:30:00Z",
  "api_key": "osk_abc123def456..."
}

Save Your API Key

The full API key is only shown once when created. Store it securely!

Using an API Key

Include the key in the X-API-Key header:

curl -H "X-API-Key: osk_abc123def456..." \
  https://api.openskip.io/api/v1/submissions

List Your API Keys

GET /api/v1/auth/api-keys

Revoke an API Key

DELETE /api/v1/auth/api-keys/{key_id}

Get Current User

Verify your authentication and get account details:

GET /api/v1/auth/me

Response: 

{
  "id": 1,
  "username": "myusername",
  "email": "user@example.com",
  "role": "contributor",
  "is_active": true,
  "is_approved": true,
  "created_at": "2024-01-15T10:30:00Z"
}

User Roles

Role Capabilities
contributor Submit timestamps, manage own account
moderator Review and approve/reject submissions
admin Full access, manage users, generate invite codes