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.

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

See also

• How to authenticate
• OAuth2 scope model