Authentication

This page documents the authentication specification for the Protime API, including OIDC discovery, token endpoints, request/response formats, and scope naming conventions.

OIDC discovery

The Protime API implements the OIDC (OpenID Connect) protocol. The discovery document is available at:

https://authentication.<environmentURL>/tenants/<tenantName>/.well-known/openid-configuration

Environment URLs

Token endpoint

https://authentication.<environmentURL>/tenants/<tenantName>/connect/token

Tokens are issued per tenant. Each token is valid for a fixed duration, expressed in seconds in the response.

Supported grant types

The API supports the OAuth 2.0 Client Credentials grant type. For step-by-step instructions on obtaining a token, see How to authenticate.

Token request format

Request headers

POST /tenants/<tenantName>/connect/token HTTP/1.1
Host: authentication.<environmentURL>
Content-Type: application/x-www-form-urlencoded

Request body parameters

Example body (application/x-www-form-urlencoded):

grant_type=client_credentials&client_id=client+specific+client+id&client_secret=client+specific+client+secret&scope=connector-protimeapi-activity-definitions.read+connector-protimeapi-activity-definitions.write+connector-protimeapi-clockings.read

Token response format

Example response:

{
    "access_token": "eyJ...Uc",
    "expires_in": 1800,
    "token_type": "Bearer",
    "scope": "connector-protimeapi-activity-definitions.read connector-protimeapi-activity-definitions.write connector-protimeapi-clockings.read"
}

Authorization header

The access token is passed via the Authorization header on every API request:

Authorization: Bearer eyJ...Uc

An expired or invalid token results in a 401 response.

Scope naming convention

Scopes follow the pattern:

connector-protimeapi-<collection>.<permission>

When no scope is specified in the token request, all scopes the client credentials are entitled to are granted by default.

Scope entitlement

Each set of client credentials is provisioned with a fixed set of entitled scopes. A token request can only ask for scopes within that set.

{
    "error": "invalid_scope"
}

The rejection applies to the whole request: valid scopes in the same request are not granted either.

Third-party integrations usually receive credentials with a deliberately limited entitlement covering only the collections they were authorised for. Such credentials are normally not entitled to the general scopes and must request per-collection scopes explicitly.

General scopes

In addition to per-collection scopes, two general scopes grant broad access across all collections:

A token carrying connector-protimeapi-all.read is accepted by any endpoint that requires a .read scope. Likewise, connector-protimeapi-all.write is accepted by any endpoint that requires a .write scope. These scopes are evaluated alongside per-collection scopes – an endpoint accepts either its specific scope or the matching general scope.

General scopes simplify token management when an integration needs access to many collections, but they reduce the security benefit of least-privilege scoping. Use per-collection scopes when possible.

Example – requesting only clocking-related scopes:

grant_type=client_credentials&client_id=client+specific+client+id&client_secret=client+specific+client+secret&scope=connector-protimeapi-clockings.read+connector-protimeapi-clockings.write

Scope reference by domain

The following tables list all available scopes grouped by domain. Not every collection supports both read and write; the available permissions reflect the operations the API exposes for each collection.

Time

Activities

People

Foundation

Planning

Access

Cross-cutting

General (all collections)

These scopes grant access across all collections, but only to credentials entitled to them. See General scopes and Scope entitlement for details.

See also

• How to authenticate
• OAuth2 scope model