Platform API

The Timefold Platform API provides management capabilities across the entire platform. It is distinct from the model APIs, which are per-model, solve-focused APIs used to submit datasets and retrieve results.

Use the Platform API when you need to automate or integrate with platform administration like configuring external map providers, or managing location sets. Model APIs, by contrast, use API keys for authentication and support only a single model’s solve operations. See API usage for details on model API authentication and usage.

Use cases

The Platform API covers several areas of platform administration, like:

  • External map provider registration: register and configure third-party map providers as an alternative to the built-in OSRM service. See Implementing an external map provider for details on what an external provider must implement.

  • Location sets management: create and manage named sets of locations to pre-compute and cache distance matrices, avoiding redundant recalculation across runs. See Location sets configuration for details.

The Platform API covers administration endpoints only. Operations such as submitting datasets, querying audit logs, managing tenants or members, and provisioning API keys are available through separate APIs. See the model API documentation for solve operations.

API specification

The Platform API is fully described in OpenAPI format:

Authentication with Personal Access Tokens

The Platform API uses Personal Access Tokens (PATs) for authentication. PATs are scoped by tenant and resource permission, giving you fine-grained control over what each token can access.

Include the token in the Authorization header of each request:

Authorization: Bearer <your-personal-access-token>

Unlike API keys, which are tenant-level credentials tied to model access, PATs are personal and belong to the user who created them.

Generating a Personal Access Token (preview)

This section describes functionality that is currently available as a preview feature. If you’d like early access to this feature, please Contact us.

  1. Click your user menu at the top right of the platform.

  2. Select Access tokens.

Access tokens overview showing the token list and the Generate new token button
Figure 1. Access tokens overview showing the token list and the Generate new token button

  1. Click Generate new token (top right of the token list).

  2. Fill in the token details:

    1. Name (required): a unique label to identify the token.

    2. Description (optional): free-text notes about the token’s purpose.

    3. Expires: select an expiry duration from the dropdown. The default is 30 days; the exact expiry date is shown.

    4. Tenants: choose All tenants or Only selected tenants. Selecting the latter reveals a checklist of available tenants.

  3. Select the permissions required for your use case.

  4. Click Generate.

Generate new token dialog showing the name, expiry, tenant scope, and permission matrix fields

After clicking Generate, a modal displays the token value exactly once.

Copy your token immediately. It won’t be shown again after you close this dialog. A read-only field displays the token string, with a copy-to-clipboard button.

Preview status

This feature is currently available as a preview feature. If you’d like early access to this feature, please Contact us.

Token permissions

Configure permissions using a matrix of resource types and access levels. All permissions are unchecked by default; select only what your use case requires.

Access levels:

Permission Allowed operations

Read

GET and list operations

Update

Modifying existing resources

Create

Creating new resources

Delete

Removing resources

Restore

Restoring previously deleted resources

The following resource types correspond to the endpoints available in the Platform API:

Permission Name Description

ExternalMapProvider

External Map Providers

Register and configure third-party map providers used for distance matrix calculations instead of the built-in OSRM service.

MapLocationSet

Map Location Sets

Create and manage named sets of locations used to pre-compute and cache distance matrices for routing models.
Follow the Principle of Least Privilege and grant only the permissions your integration actually needs.

Managing tokens

You can find all tokens belonging to your user account at User menu > Access tokens. The list shows each token’s name, creation date, last used date, expiry, and status.

Tokens are personal and aren’t shared across users. To revoke a token, use the row-level actions in the token list.