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 available scopes are granted by default. Narrowing scopes to only the required permissions is recommended.

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. See General scopes for details.

See also

• How to authenticate
• OAuth2 scope model