Getting Started

Learn how to authenticate and make your first API request.

Base URL

All API requests should be made to the following base URL:

https://api-next.checkio.co.uk

Authentication

The Checkio API uses Bearer token authentication. Include your JWT token in the Authorization header:

Authorization: Bearer <your-token>

Obtaining a Token

There are two ways to obtain an access token:

OAuth 2.0 Flow

For user authentication, redirect to the login endpoint and handle the callback to receive tokens via HTTP-only cookies.

Client Credentials

For server-to-server authentication, use your API credentials to obtain a token directly.

Quick Example

Here's a simple example of making an authenticated request to get your profile:

curl -X GET 'https://api-next.checkio.co.uk/v1/my/profile' \
  -H 'Authorization: Bearer <your-token>'

Response

{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "totpEnabled": true,
  "createdAt": "2024-01-15T10:30:00Z"
}

Tenant Context

Most API operations require a tenant context. Tenant-scoped endpoints include the tenant ID in the URL path:

https://api-next.checkio.co.uk/{tenantId}/v1/credit-reports

You can list your available tenants and select one using the My Account endpoints:

# List your tenants
curl -X GET 'https://api-next.checkio.co.uk/v1/my/tenants' \
  -H 'Authorization: Bearer <your-token>'

# Select a tenant
curl -X POST 'https://api-next.checkio.co.uk/v1/my/tenants/select' \
  -H 'Authorization: Bearer <your-token>' \
  -H 'Content-Type: application/json' \
  -d '{"tenantId": "your-tenant-id"}'

Credits System

Many API operations consume credits from your tenant's wallet. The credit cost is included in the response metadata:

{
  "meta": {
    "request": {
      "timeTakenMs": 1234
    },
    "wallet": {
      "balance": 10000,
      "cost": 100
    }
  },
  "data": { ... }
}

Pricing: 10 credits = £0.01

Rate Limiting

API requests are subject to rate limiting. If you exceed the limit, you'll receive a 429 Too Many Requests response.

Contact support if you need higher rate limits for your use case.

Error Handling

The API returns consistent error responses with a code and message:

{
  "code": "insufficient-credits",
  "message": "Your wallet balance is insufficient for this operation"
}

Common Error Codes

HTTP Status	Description
`400`	Bad request - invalid parameters
`401`	Unauthorized - invalid or missing token
`403`	Forbidden - insufficient permissions
`404`	Not found - resource doesn't exist
`402`	Payment required - insufficient credits
`429`	Too many requests - rate limited