Skip to content
Tiketti Docs

Authentication

This content is not available in your language yet.

The Tiketti API uses JWT (JSON Web Token) authentication with access and refresh tokens.

Token Types

TokenLifetimeUse
Access Token15 minutesAPI requests
Refresh Token7 daysGet new access tokens

Obtaining Tokens

Login

Exchange credentials for tokens:

Terminal window
POST /api/v1/auth/login
Content-Type: application/json


{
  "email": "user@example.com",
  "password": "your_password"
}

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2...",
  "token_type": "bearer",
  "expires_in": 900,
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "user@example.com",
    "name": "John Doe"
  }
}

Refresh Token

Get a new access token when the current one expires:

Terminal window
POST /api/v1/auth/refresh
Content-Type: application/json


{
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2..."
}

Response:

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

Using Access Tokens

Include the access token in the Authorization header:

Terminal window
curl https://api.tiketti.app/api/v1/tickets \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Organization Context

Users may belong to multiple organizations. Specify which organization to use:

Via Header

Terminal window
X-Organization-Id: 123e4567-e89b-12d3-a456-426614174000

Get User’s Organizations

Terminal window
GET /api/v1/auth/me
Authorization: Bearer <token>

Response:

{
  "id": "...",
  "email": "user@example.com",
  "name": "John Doe",
  "organizations": [
    {
      "id": "org-1-uuid",
      "name": "Acme Corp",
      "role": "admin"
    },
    {
      "id": "org-2-uuid",
      "name": "Widget Co",
      "role": "agent"
    }
  ]
}

Logout

Invalidate the current refresh token:

Terminal window
POST /api/v1/auth/logout
Authorization: Bearer <access_token>
Content-Type: application/json


{
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2..."
}

Token Security

Best Practices

  • Never expose tokens in URLs or logs
  • Store tokens securely (httpOnly cookies, secure storage)
  • Use HTTPS for all API requests
  • Refresh tokens before they expire
  • Logout to invalidate tokens when done

Token Contents

Access tokens are JWTs containing:

{
  "sub": "user-uuid",
  "email": "user@example.com",
  "exp": 1640000000,
  "iat": 1639999100,
  "org_id": "org-uuid",
  "role": "admin"
}

API Keys (Coming Soon)

For server-to-server integrations, API keys provide a simpler authentication method:

Terminal window
Authorization: ApiKey sk_live_abc123...

API keys will have:

  • Configurable permissions
  • No expiration (until revoked)
  • Audit logging

Error Handling

Invalid Credentials

{
  "error": {
    "code": "INVALID_CREDENTIALS",
    "message": "Email or password is incorrect"
  }
}

Expired Token

{
  "error": {
    "code": "TOKEN_EXPIRED",
    "message": "Access token has expired"
  }
}

Handle by refreshing the token and retrying the request.

Invalid Token

{
  "error": {
    "code": "INVALID_TOKEN",
    "message": "Token is invalid or malformed"
  }
}

Example: Complete Auth Flow

  1. Login to get tokens

    Terminal window
    POST /api/v1/auth/login
    → access_token, refresh_token

  2. Make API requests with access token

    Terminal window
    GET /api/v1/tickets
    Authorization: Bearer <access_token>

  3. When access token expires, refresh it

    Terminal window
    POST /api/v1/auth/refresh
    → new access_token

  4. When done, logout

    Terminal window
    POST /api/v1/auth/logout