We currently support OAuth2 client_credentials and password_grant authentication
Request an access token
Client Credentials Grant
The Client Credentials grant type is used by clients to obtain an access token outside of the context of a user - usually this is recommended for machine to machine (M2M) communications. You will have to POST client credentials in order to directly receive an access token which you will use in subsequent requests to access protected resources.
- Request method: POST
- URI: /<account>/auth/oauth2/token
- Header:
- Content-Type: application/x-www-form-urlencoded
- Parameter:
- grant_type: The OAuth2 grant type to use – here “client_credentials”
- client_id: Your Clients ID on the backend
- client_secret: Your Clients Secret (key/password)
You need to create your client id and secret in your TimeTac application --> to do so go to your account settings and find "API Credentials"
Example HTTP Request:
POST //auth/oauth2/token HTTP/1.1
Host: api-sandbox.timetac.com (https://api-sandbox.timetac.com/)
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&client_id=CLIENT__API_USER_xxx&client_secret=XXX
Example Server Response:
{
"access_token": "5256xxxxxxxxxxxxxxxxxxxxxxxx140f",
"token_type": "bearer",
"expires_in": 3600
}
Password Grant
The password grant is a type where you will have to POST both user credentials and client credentials in order to directly receive an access token for the user, without going through the process of requesting a request token or asking for user consent.
This grant type is not supported by the API credentials you created yourself. To use the 'password' grant type, please contact our support team to request specific API credentials, which will include a username, password, client_id, and client_secret.
- Request method: POST
- URI: /<account>/auth/oauth2/token
- Header:
- Content-Type: application/x-www-form-urlencoded
- Parameter:
- grant_type: The OAuth2 grant type to use – here “password”
- client_id: Your Clients ID on the backend — ask an admin/support.
- client_secret: Your Clients Secret (key/password) — ask an admin/support.
- username: The TimeTac username of the user to authenticate
- password: The password of the TimeTac user to authenticate
Example HTTP Request:
POST //auth/oauth2/token HTTP/1.1
Host: api-sandbox.timetac.com (https://api-sandbox.timetac.com/)
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded
grant_type=password&username=manager&password=1xxxxxxxxxxxxxxxxxxxxxxxx6&client_id=TT_NATIV
Example Server Response:
{
"access_token": "5256xxxxxxxxxxxxxxxxxxxxxxxx140f",
"token_type": "bearer",
"expires_in": 3600,
"refresh_token": "264fxxxxxxxxxxxxxxxxxxxxxxxx57e8"
}
You will have to remember both, the access_token as well as the refresh_token, or else you will have to send the user credentials again once the access_token expires.
Once the access_token is expired, you will no longer have access to the API, and will receive an error response on further requests:
{
"error_description": "The provided access token is invalid.",
"error": "invalid_request"
}
From here on, you will have to either request a new access_token with another password_grant, or “refresh” your access with the previous refresh_token.
Refresh an access token
If you have the corresponding refresh_token for an expired access_token, you can request a new acces_token without the need to send the user credentials again.
Request method: POST
URI: //auth/oauth2/token
Header: Content-Type: application/x-www-form-urlencoded
Parameter:
grant_type: The OAuth2 grant type to use – here "refresh_token"
client_id: Your Clients ID on the backend -- ask an admin/support.
client_secret: Your Clients Secret (key/password) -- ask an admin/support.
refresh_token: A valid refresh token
Example HTTP Request:
{
"access_token": "7053xxxxxxxxxxxxxxxxxxxxxxxx066c",
"token_type": "bearer",
"expires_in": 3600,
"refresh_token": "fc7dxxxxxxxxxxxxxxxxxxxxxxxxaf61"
}
You will receive a new token response, with a new access_token and refresh_token to use.
Example Server Response:
{
"access_token": "7053xxxxxxxxxxxxxxxxxxxxxxxx066c",
"token_type": "bearer",
"expires_in": 3600,
"refresh_token": "fc7dxxxxxxxxxxxxxxxxxxxxxxxxaf61"
}
Authorize an API request
Once you have aquired an access_token, you can use it to authorize an API request. The request itself depends on the resource you want to query and the action you want to perform, but the authorization is always done via the “Authorization” header:
- Header:
- Authorization: Bearer <access_token>
Example HTTP Request:
GET //v4/user/read/?hr_manager=1&active=1 HTTP/1.1
Host: api-sandbox.timetac.com
Authorization: Bearer 7053xxxxxxxxxxxxxxxxxxxxxxxx066c
Cache-Control: no-cache
Example Server Response:
{
"Host": "api-sandbox.timetac.com",
"Success": true,
"NumResults": 0,
"ResourceName": "User",
"Results": []
}