Authentication

MatchEngine API uses token-based authentication. There are two types of authentication:

  1. User Authentication - For end-users with their own accounts
  2. Client API Authentication - For third-party applications (B2B integration)

Token Authentication

Include the token in the Authorization HTTP header, prefixed with Token:

Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

Unauthenticated requests will receive: - 401 Unauthorized response - WWW-Authenticate: Token header

Example Request

curl -X GET "https://api.matchengine.de/api/v1/bookings/" \
  -H "Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b"

User Authentication

For end-users accessing their own data (bookings, profile, etc.).

Obtain User Token

Request:

POST /api/v1/api-token-auth/

Parameters:

Name Type Description
username string User's username or email
password string User's password

Response:

{
    "token": "9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b"
}

Store this token securely and include it in all subsequent API requests.

Client API Authentication

For third-party applications that create bookings on behalf of users.

Client API Token

Client API tokens are issued by MatchEngine. Contact us to obtain your credentials.

Authorization: Token YOUR_CLIENT_API_TOKEN

User Identification Headers

When making requests on behalf of a user, include one of these headers:

Header Description
X-User-External-ID Your application's ID for the user
X-User-ID MatchEngine's UUID for the user

Example:

curl -X POST "https://api.matchengine.de/api/v1/bookings/" \
  -H "Authorization: Token YOUR_CLIENT_API_TOKEN" \
  -H "X-User-External-ID: your-user-123" \
  -H "Content-Type: application/json" \
  -d '{...}'

User Registration

Before making requests on behalf of users, register them with your Client API:

curl -X POST "https://api.matchengine.de/api/v1/client/users/register/" \
  -H "Authorization: Token YOUR_CLIENT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "your-user-123",
    "email": "user@example.com"
  }'

See Client API for complete documentation.

Public Endpoints

Some endpoints do not require authentication:

Endpoint Description
GET /api/v1/venues/ List public venues
GET /api/v1/venues/{id}/ Get venue details
GET /api/v1/resources/ List resources
GET /api/v1/resources/{id}/ Get resource details
GET /api/v1/resources/availability/ Get resource availability

Error Responses

401 Unauthorized

Invalid or missing token:

{
    "detail": "Authentication credentials were not provided."
}

Or:

{
    "detail": "Invalid token."
}

403 Forbidden

Valid token but insufficient permissions:

{
    "detail": "You do not have permission to perform this action."
}

For Client API requests without user identification:

{
    "error": "User identification required. Provide X-User-ID or X-User-External-ID header."
}