Authentication
All API endpoints require an OAuth access token.
Access tokens can generally be obtained by following these steps:
- Register an application here to obtain a client_id and client_secret.
- Redirect the user to https://swiftapp.com/oauth/authorize, using the client_id, scope and redirect_uri parameters to pass your client ID and the page you would like to redirect to upon acquiring an access token.
- The user will be prompted to authorise your application and if authorised, the user will be directed to the page specified in the redirect_uri parameter. An authorization_code parameter will be appended to this request.
- Pass the authorization_code to the /oauth/token API endpoint to acquire an OAuth access token.
Authorization Endpoint
Endpoint | Description |
|---|---|
| https://swiftapp/oauth/authorize | Initial step in . |
Request Parameters
Parameter | Description |
|---|---|
response_type | Either code or token. What to return, an authorization_code or access_token for implicit authorization grants. |
client_id | The client identifier provided when registering the application. |
redirect_uri | The url to redirect the user to when authorization is granted. Must match the redirect url provided when registering the application. |
scope | The level of access to the account being requested. |
state | Any client defined string that will be passed on to redirect_uri. |
Response
The authorization server will redirect the user to the redirect_uri provided with the following parameters:
Parameter | Description |
|---|---|
code | The authorization code to be exchanged via the token end point for an authorization token. |
state | The value of the state parameter given by the client in the authorization request. |
Access Token Endpoint
Endpoint | Description |
|---|---|
oauth/token | Used to exchange an authorization grant or refresh token for an access token. |
Basic HTTP authentication is required for this end point. The username and password are the client_id and client_secret for the client application.
Request Parameters
Parameter | Description |
|---|---|
grant_type | authorisation_code, password or refresh_token. Password grant_type is not generally available and most applications will use an authorisation_code grant type. |
code | The authorization code received from the authorisation endpoint. |
refresh_token | The refresh token issued to the client. |
username | For password grant type, the account's username. |
password | For password grant type, the account's password. |
redirect_uri | The redirect_uri that was sent to the authorization endpoint. |
client_id | Client identifier for the application requesting authorization. |
state | Any client defined string that will be passed on to redirect_uri. |
Response
Parameter | Description |
|---|---|
access_token | Access token to be used for accessing API resources. |
token_type | The authorization code received from the authorisation endpoint. |
expires_in | Duration in seconds after which the access_token will expire. |
refresh_token | Token to be used to retrieve a new access_token when the current on expires. |
scope | Level of access for the access_token. |