Authentication

General

Protime implements OIDC (Open ID Connect) protocol to authenticate a user.

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

  • <environmentURL>
    • Production: myprotime.eu
    • Sandbox: myprotimesandbox.eu
  • <tenantName>

Get access token

To get an access token for our application, you need to send a POST request to

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

These tokens will be per tenant. A token will be valid for 30 mins, which is given in the response in seconds.

Headers:

{
	"Content-Type":"application/x-www-form-urlencoded"
}

Body (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"
}

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"
}

Use the access token

Set the bearer token in your Authorization header for each request:

{
	"Authorization":"Bearer eyJ...Uc"
}

Best Practices:

Token expiration time

A token will be valid for 30 mins. Reuse this token for multiple api-calls instead of regenerating a token per call. This could result in rate limiting for the application.

If a bearer token is expired or not valid anymore a response code of 401 will be returned on which a new token should be generated.

Scope

A scope defines the specific permissions or access levels granted to a token. It determines what actions or data the token can access within the Protime API.
By default, when no scope is given, all the available scopes will be present on your token. However, to make it more secure, it is advised to narrow it down. Think about the granularity of these scopes when requesting access tokens.
The necessary scopes can be found with the endpoints in Swagger.

eg: only clocking-related scopes are needed
Body (x-www-form-urlencoded):

{
	"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"
}

Response:

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