All API requests must contain way to authenticate the user and authorize access to requested data. Weekdone
API supports OAuth 2.0 Authentication mechanism. A web application
with a user's authorization key, may access information and make changes to data stored in Weekdone as if it were that user.
OAuth 2.0
Weekdone API supports only Authorization Code Grant
flow of the OAuth 2.0 framework. This is the most common strategy for traditional web applications and native desktop/mobile
apps.
Registering your application
Before starting to implement the Weekdone API a new app must be registered with Weekdone to receive
Client ID and Client Secret . This can be done
from Applications page. All applications added by a client are visible to all admin level
accounts of that client.
As with all OAuth apps, you must supply an Application URL as well as a
Redirect URL that successful (or failed) authentications will redirect to.
Requesting authorization from the user
Developers should use button with the text "Sign in with Weekdone" when redirecting users to Weekdone to start authorization
flow.
To start the authorization flow users must be redirected to https://weekdone.com/oauth_authorize passing parameters in query string.
Name |
Required |
Description |
client_id |
yes |
The Client ID uniquely identifies the application making the request. |
redirect_uri |
yes |
The URI to redirect to on success or error. This must match the Redirect URL specified in the application settings. |
response_type |
yes |
Must be 'code' (as other authorization flows are not supported). |
state |
no |
Encodes state of the app, which will be returned verbatim in the response and can be used to match the response up to a given request. |
If either the client_id or redirect_uri do not
match, the user will simply see a plain-text error. Otherwise, all errors will be sent back to the
redirect_uri specified.
The user then sees a screen giving them the opportunity to accept or reject the request for authorization. In either case, the user
will be redirected back to the redirect_uri .
Response back to application
User will be redirected back to redirect_uri
with following parameters in the query string on successful authorization:
Name |
Description |
code |
This is the code your app can exchange for a token |
state |
The state parameter that was sent with the authorizing request |
Token exchange
If user granted access to the application the code received by application must be exchanged for proper access token. The app
must make POST request to https://weekdone.com/oauth_token
passing following parameters in form-encoded post body:
Name |
Required |
Description |
code |
yes |
The code you are exchanging for an auth token |
grant_type |
yes |
Must be authorization_code |
client_id |
yes |
The Client ID uniquely identifies the application making the request. |
client_secret |
yes |
The Client Secret belonging to the app, found in application details |
redirect_uri |
yes |
Must match the redirect_uri specified in the original request |
Token exchange response
In the response, you will receive a JSON payload with the following parameters:
Name |
Description |
access_token |
The token to use in future requests against the API |
refresh_token |
If exchanging a code, a long-lived token that can be used to get new access tokens when old ones expire. |
user |
A JSON object encoding a few key fields about the logged-in user |
Requesting new access token with refresh token
access_token will expire in 60 minutes and new tokens must be requested using
refresh_token . To request new access token the app
must make POST request to https://weekdone.com/oauth_token
passing following parameters in form-encoded post body:
Name |
Required |
Description |
refresh_token |
yes |
The refresh_token |
grant_type |
yes |
Must be refresh_token |
client_id |
yes |
The Client ID uniquely identifies the application making the request. |
client_secret |
yes |
The Client Secret belonging to the app, found in application details |
redirect_uri |
yes |
Must match the redirect_uri specified in the original request |
Response will be the new access_token
Tips to get you started
There are several OAuth libraries to get you started
We have Zapier integration available if you are already using
Zapier
|