Token Operations

curl -X POST "https://api.tktchurch.com/v1/auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
  }'

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_in": 3600,
  "token_type": "bearer"
}

{
  "sub": "123e4567-e89b-12d3-a456-426614174000",
  "scopes": ["event:read", "user:read"],
  "exp": "2024-01-01T00:00:00Z",
  "iat": "2023-12-31T00:00:00Z",
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe",
    "status": "active",
    "provider": "google",
    "providerInfo": {
      "providerId": "google123",
      "displayName": "John Doe",
      "photoUrl": "https://example.com/photo.jpg",
      "email": "[email protected]"
    },
    "lastLoginAt": "2024-01-20T08:30:00Z",
    "roles": [
      {
        "id": "456e4567-e89b-12d3-a456-426614174000",
        "name": "Member",
        "description": "Regular church member",
        "permissions": ["event:read", "newsletter:read", "livestream:read"],
        "isSystem": true
      }
    ],
    "createdAt": "2023-12-01T00:00:00Z"
  }
}

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_in": 3600,
  "token_type": "bearer",
  "is_new_user": false
}

{
  "error": {
    "status": 400,
    "reason": "Refresh token is required"
  }
}

{
  "error": {
    "status": 401,
    "reason": "Invalid refresh token"
  }
}

{
  "error": {
    "status": 403,
    "reason": "Provider not linked. Use /auth/link-provider to link this provider."
  }
}

POST

auth

token

curl -X POST "https://api.tktchurch.com/v1/auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
  }'

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_in": 3600,
  "token_type": "bearer"
}

{
  "sub": "123e4567-e89b-12d3-a456-426614174000",
  "scopes": ["event:read", "user:read"],
  "exp": "2024-01-01T00:00:00Z",
  "iat": "2023-12-31T00:00:00Z",
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe",
    "status": "active",
    "provider": "google",
    "providerInfo": {
      "providerId": "google123",
      "displayName": "John Doe",
      "photoUrl": "https://example.com/photo.jpg",
      "email": "[email protected]"
    },
    "lastLoginAt": "2024-01-20T08:30:00Z",
    "roles": [
      {
        "id": "456e4567-e89b-12d3-a456-426614174000",
        "name": "Member",
        "description": "Regular church member",
        "permissions": ["event:read", "newsletter:read", "livestream:read"],
        "isSystem": true
      }
    ],
    "createdAt": "2023-12-01T00:00:00Z"
  }
}

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_in": 3600,
  "token_type": "bearer",
  "is_new_user": false
}

{
  "error": {
    "status": 400,
    "reason": "Refresh token is required"
  }
}

{
  "error": {
    "status": 401,
    "reason": "Invalid refresh token"
  }
}

{
  "error": {
    "status": 403,
    "reason": "Provider not linked. Use /auth/link-provider to link this provider."
  }
}

This endpoint handles various token-related operations including token refresh, token information retrieval, and social authentication through JWT tokens.

Request Body

string

required

The type of token operation to perform:

refresh_token: Get new access token using refresh token
token_info: Get information about an access token
id_token: Authenticate with a social provider’s ID token

string

Required when grant_type is “refresh_token”. The refresh token to use for obtaining a new access token.

string

Required when grant_type is “token_info”. The access token to get information about.

string

Required when grant_type is “id_token”. The ID token from a social provider.

Response

string

JWT access token (for refresh_token and id_token grant types)

string

JWT refresh token (for refresh_token and id_token grant types)

integer

Token expiration time in seconds (default: 3600)

string

Type of token (always “bearer”)

boolean

Only present for id_token grant type. Indicates if a new user was created.

Token Info Response

When using token_info grant type, the response includes:

string

User ID associated with the token

array

List of permissions granted to the token.

string

Token expiration timestamp

string

Token issued at timestamp

object

Show User Object

string

User’s unique identifier (UUID)

string

required

User’s email address

string

User’s first name

string

User’s last name

string

required

User’s account status. One of:

active: User is active and can access the system
inactive: User is inactive (unverified email or deactivated account)
suspended: User is temporarily suspended

string

required

Authentication provider. One of:

local: Local authentication using email and password
google: Google OAuth authentication
facebook: Facebook OAuth authentication
apple: Apple Sign In authentication

object

Provider-specific user information

Show Provider Info

string

The provider’s unique identifier for the user

string

The user’s display name from the provider

string

URL to the user’s profile photo

string

The user’s email from the provider

Timestamp of last login

array

List of user roles

Show Role Object

string

Role identifier (UUID)

string

required

Role name

string

required

Role description

array

required

List of permissions granted to this role

boolean

required

Whether this is a system-defined role

string

Account creation timestamp

When using id_token grant type, the endpoint:

Token Verification:
- Verifies the ID token signature using provider’s JWKS
- Validates token claims (iss, aud, exp, iat)
- Extracts user information from token payload
Provider Validation:
- Google tokens must be issued by https://accounts.google.com
- Apple tokens must be issued by https://appleid.apple.com
- Client ID validation against environment configuration
Account Processing:
- Checks for existing account with email
- Link the account to the provider if it exists, ensuring the primary provider matches before establishing the connection.
- Creates new account if email is new
- Assigns default member role to new accounts

Error Responses

object

Error details when the request fails

Show Error Object

integer

HTTP status code

string

Error message explaining why the request failed

Common error cases:

400 Bad Request: Missing required fields or invalid grant type
401 Unauthorized: Invalid/expired tokens or provider verification failed
403 Forbidden: Provider not linked or insufficient permissions

curl -X POST "https://api.tktchurch.com/v1/auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
  }'

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_in": 3600,
  "token_type": "bearer"
}

{
  "sub": "123e4567-e89b-12d3-a456-426614174000",
  "scopes": ["event:read", "user:read"],
  "exp": "2024-01-01T00:00:00Z",
  "iat": "2023-12-31T00:00:00Z",
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe",
    "status": "active",
    "provider": "google",
    "providerInfo": {
      "providerId": "google123",
      "displayName": "John Doe",
      "photoUrl": "https://example.com/photo.jpg",
      "email": "[email protected]"
    },
    "lastLoginAt": "2024-01-20T08:30:00Z",
    "roles": [
      {
        "id": "456e4567-e89b-12d3-a456-426614174000",
        "name": "Member",
        "description": "Regular church member",
        "permissions": ["event:read", "newsletter:read", "livestream:read"],
        "isSystem": true
      }
    ],
    "createdAt": "2023-12-01T00:00:00Z"
  }
}

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_in": 3600,
  "token_type": "bearer",
  "is_new_user": false
}

{
  "error": {
    "status": 400,
    "reason": "Refresh token is required"
  }
}

{
  "error": {
    "status": 401,
    "reason": "Invalid refresh token"
  }
}

{
  "error": {
    "status": 403,
    "reason": "Provider not linked. Use /auth/link-provider to link this provider."
  }
}

Documentation

Authentication

Devices

Livestreams

Files

Events

Newsletters

Request Body

Response

Token Info Response

Error Responses

​Request Body

​Response

​Token Info Response

​Social Authentication Flow

​Error Responses

Request Body

Response

Token Info Response

Social Authentication Flow

Error Responses