BigTime's OAuth 2.0 api provides secure access to user's resources for third-party
app without sharing their credentials.
Getting an authorization code.
To receive an authorization code redirect user to request BigTime access.
HTTP GET: /oauth2/authorize?client_id={ClientId}&redirect_uri={RedirectUri}
User will be redirected to BigTime authentication page.
Once BigTime has successfully authenticated the user, your app will be authorized
and you will be redirected to redirect_uri with the authorization code.
HTTP/1.1 302 Found
Location: https://{redirect_uri}?code={AuthorizationCode}
Field
|
Type
|
Description
|
client_id
|
String
|
ID of registered in BigTime client app that requests access to user resources. It
generated automatically and can be found on app configuration page.
|
redirect_uri
|
String
|
The URL in your client app where users will be sent after authorization.
|
code
|
String
|
Temporary code that indicates that client app is authorized by the user. Use it
to exchange for access token.
|
Exchanging the authorization code for access token.
To receive access token submit a simple query to this api, passing in the authorization
code, client_id, client_secret and grant_type.
HTTP POST: /oauth2/accesstoken
POST CONTENT: {client_id: 123456789, client_secret: 987654321, code: 192837465, grant_type: "authorization_code"}
HTTP RESPONSE: {access_token: 1q2w34r5t, refresh_token: 5t6y7u8i, expires_in: 264960}
Field
|
Type
|
Description
|
client_id
|
String
|
ID of registered in BigTime client app that requests access to user resources. It
generated automatically and can be found on app configuration page.
|
client_secret
|
String
|
Secret of registered in BigTime client app that requests access to user resources.
It generated automatically and can be found on app configuration page.
|
code
|
String
|
Temporary code that indicates that client app is authorized by the user. Obtained
on previous step.
|
grant_type
|
String
|
The type of grant the code relates to. Either "authorization_code" or "refresh_token".
In this case, set value to "authorization_code".
|
access_token
|
String
|
Long-term token that gains client app access to BigTime resources on behalf of user.
Provide it to request to BigTime api.
|
refresh_token
|
String
|
Token generated by BigTime during the authorization exchange. Use it to obtain new
access_token
|
expires_in
|
Integer
|
The expiration time of access token in minutes. By default, equals to 6 months.
|
Error
|
Description
|
invalid_request
|
A required parameter is missing.
|
invalid_client
|
Client cannot be authenticated. For example, if the client_id or client_secret are
incorrect or invalid.
|
invalid_grant
|
Auth code doesn’t exist or is invalid for the client. The authorization code has
expired. Server does not support the grant_type specified. You should ensure that
the grant_type in your request is "authorization_code" or "refresh_token".
|
server_error
|
BigTime could not proccess your request. If the problem persists contact support
at support@bigtime.net.
|
Making an API call.
Provide received access token to header request to access user resources.
HEADERS: Authorization=Bearer {access_token}
HTTP GET: /project?{ShowInactive=true}
or using url param for GET requests
HTTP GET: /project?{ShowInactive=true}&access_token={access_token}
Field
|
Type
|
Description
|
access_token
|
String
|
Long-term token that gains client app access to BigTime resources on behalf of user.
Provide it to request to BigTime api.
|
Refreshing access token.
During the authorization exchange, you are issued with an access token and a refresh
token. You can use the refresh token to obtain a new access token without the user
having to sign in again to allow access. To do this, send a POST request to:
HTTP POST: /oauth2/accesstoken
POST CONTENT: {client_id: 123456789, client_secret: 987654321, grant_type: "refresh_token", refresh_token: 5t6y7u8i}
HTTP RESPONSE: {access_token: 7new89token, refresh_token: 5t6y7u8i, expires_in: 264960}
Field
|
Type
|
Description
|
client_id
|
String
|
ID of registered in BigTime client app that requests access to user resources. It
generated automatically and can be found on app configuration page.
|
client_secret
|
String
|
Secret of registered in BigTime client app that requests access to user resources.
It generated automatically and can be found on app configuration page.
|
refresh_token
|
String
|
Token generated by BigTime during the authorization exchange. Use it to obtain new
access_token
|
access_token
|
String
|
Refreshed token that gains client app access to BigTime resources on behalf of user.
Provide it to request to BigTime api. Old one is not available anymore.
|
grant_type
|
String
|
The type of grant the code relates to. Either "authorization_code" or "refresh_token".
In this case, set value to "refresh_token". Default value is "authorization_code".
|
expires_in
|
Integer
|
The expiration time of access token in minutes. By default, equals to 6 months.
|
Error
|
Description
|
invalid_request
|
A required parameter is missing.
|
invalid_client
|
Client cannot be authenticated. For example, if the client_id or client_secret are
incorrect or invalid.
|
invalid_grant
|
Server does not support the grant_type specified. You should ensure that the grant_type
in your request is "authorization_code" or "refresh_token".
|
server_error
|
BigTime could not proccess your request. If the problem persists contact support
at support@bigtime.net.
|