Security

This set of API enables developers to :

• get/create/revoke oauth2.0 token for synthesio users. Each token is associated with a user and a set of permissions.

• Manage users and their permissions

Oauth workflow

Create token with password grant_type

This workflow MUST be done on the server side to avoid exposing user/client credentials in public code.

This workflow MUST NOT be used if any other workflow (authorization_code or implicit) can be used.

Form parameters :

Parameter	Optional	Description
grant_type	NO	Must be set to “password” in order to use that workflow
username	NO	The generated token will be associated to this user. All actions will be done on their behalf
password	NO	Password of the user
client_id	NO	Client ID given by Synthesio when requesting the app
client_secret	NO	Client secret given by Synthesio when requesting the app
scope	NO	Scope requested for that token. Must be included in the scopes of the OAuth application. Should usually be “read”

Request example

POST https://rest.synthesio.com/security/v2/oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=johndoe&password=hideme&client_id=e969e283b1639df243d20079&client_secret=bf63e88e0dd21ec00cbe3462&scope=read

Response examples

HTTP/1.1 201 Created
Content-Type: application/json

{
 "app_id": "e969e283b1639df243d20079",
 "access_token": "ee36cb3233070f9bd9a66d6a",
 "token_type": "Bearer",
 "refresh_token": "28dc6b4d4c4fa0fb27d48b3a",
 "expires_in": 10800,
 "scope": "read"
}

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
 "error": "invalid_grant",
 "error_description": "The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client",
 "details": "Login is not valid"
}

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
 "error": "invalid_grant",
 "error_description": "The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client",
 "details": "User has been deactivated"
}

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
 "error": "invalid_grant",
 "error_description": "The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client",
 "details": "Password is no longer valid"
}

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
 "error": "invalid_grant",
 "error_description": "The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client",
 "details": "User has been locked"
}

Users

Get user me

Get the user profile associated with the authorization token sent through header. The json returned contained all the fields of the user’s profile and the token currently used by this user to access API.

If the token is not valid, a 403 error is sent.

Request example

GET https://rest.synthesio.com/security/v2/me HTTP/1.1
Authorization: Bearer theaccesstoken

Response example

HTTP/1.1 200 Ok
Content-Type: application/json

{
 "data": {
  "id": "1234",
  "login": "your@email.com",
  "email": "your@email.com",
  "client_id": "5678",
  "activated": true,
  "logged_at": "2017-07-12T18:06:16Z",
  "pwd_expires_at": "2017-07-15T11:41:56Z",
  "token": {
   "app_id": "e969e283b1639df243d20079",
   "app_client_id": "4567",
   "access_token": "26c00389877e0663ad881301",
   "expires_in": 1079,
   "scope": "read"
  }
 }
}

HTTP/1.1 403 Not authorized
Content-Type: application/json

{
 "errors": [
  {
   "status": 401,
   "title": "Unauthorized",
   "detail": "Failed to authenticate oauth token"
  }
 ]
}