Authentication

OAuth 2.0 Password Grant#

Synthesio uses the OAuth 2.0 protocol for authentication and authorization. The API supports the "password" grant type, which allows you to obtain an access token using your Synthesio user credentials.

Request an access token by making a POST request to the Synthesio Security API's token endpoint. You will need to provide your Synthesio username, password, client ID, and client secret in the request body, encoded as form data (application/x-www-form-urlencoded content type).

The client ID and client secret are provided to you when you request access to the Synthesio API. The username is usually an email address, and the password is the password of the corresponding account.

You may create a dedicated Synthesio user account for API access, which can be used to generate an access token without exposing your personal credentials.

curl -X POST https://rest.synthesio.com/security/v2/oauth/token \
    -H "Content-Type: application/x-www-form-urlencoded" \
	--data-urlencode "grant_type=password" \
	--data-urlencode "username=first.last@example.com" \
	--data-urlencode "password=MyPassword123!" \
	--data-urlencode "client_id=your_client_id" \
	--data-urlencode "client_secret=your_client_secret" \
	--data-urlencode "scope=read"

{
    "app_id": "d8tao22c82cc070td2u0",
    "access_token": "b77e964471e2ced59748ec52",
    "token_type": "Bearer",
    "refresh_token": "13b95e9cd1c00d0b0866db12",
    "expires_in": 28800,
    "scope": "read"
}

Using the Access Token#

Once you have obtained an access token, you can use it to authenticate your requests to the Synthesio API. Include the access token in the Authorization header of your requests, using the Bearer scheme.

curl -X POST https://api.synthesio.com/v1/projects/123456/mentions/_search \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer b77e964471e2ced59748ec52" \
    -d '{"filters": {"language": {"values": ["eng"]}}}'

The access token is valid for an unlimited number of requests, but will expire after some time (see expires_in in the response, in seconds). You will need to request a new access token when the current one expires.