Identity and Access Management (Sep 21, 2021 1:47:19 PM)

Download OpenAPI specification:Download

Welcome to Synerise API Reference! We hope that you'll enjoy your stay here.

If you need help with our services, feel free to contact us at support@synerise.com.

Authentication

JWT

Synerise uses JSON Web Token (JWT) as the authorization method. The token is generated by the auth/login endpoint. You need to include it in the Authorization header of your requests, with a Bearer prefix. See this simplified example of a call:

curl -X GET https://api.synerise.com/v4/clients \
-H 'Accept: application/json' \
-H 'Api-Version: 4.4' \
-H 'Authorization: Bearer eyJhbGciOiJSzZXIiLCJjdGQiOjE1NTI0NjMzMjg4NjIsImF1dGgiOiJINHNJQUFBQUFBQUFBSXVPQlFBcHUwd05BZ0FBQUE9PSIsIm5tZSI' \
-H 'Content-Type: application/json'

Remember to include a space between Bearer and the token.

The token is valid for one hour (unless configured differently). You can request a refreshed key for the session by using the auth/refresh endpoint before the current token expires.

You can verify your JWT signature by using the public key.

Security Scheme Type HTTP
HTTP Authorization Scheme bearer

apiKey

Authorization by API key sent in an X-Api-Key header. Remember to use an API key with the consumer scope and permissions appropriate for the endpoint you're using.

Security Scheme Type API Key
Header parameter name: X-Api-Key

Authorization

Methods to authorize and obtain JWT token required by our API endpoints

Authenticate anonymously

Obtain a new JWT for an anonymous Client (without an existing Client profile). The token can be used and refreshed in the same way as tokens of registered Clients.

  • This method does not require a Synerise authorization token.
Request Body schema: application/json
apiKey
string

Client API key (same as for Client login)

deviceId
string

Unique Android or iOS device ID

uuid
string

UUID of the Client

Responses

200

Anonymous authorization token

401

Unauthorized

post /auth/login/client/anonymous
https://api.synerise.com/sauth/auth/login/client/anonymous

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "apiKey": "string",
  • "deviceId": "string",
  • "uuid": "07243772-008a-42e1-ba37-c3807cebde8f"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "token": "eyJhbGciOiJSUzUxMiJ9.eyJzdinvalidwYmZkM2FkNDg2ZjQ3ZGRiMjE5MSIsImF1ZCI6IkFQSSIsInJsbSI6ImFub255bW91c19jbGllbnQiLCJjdGQiOjE1NTMwMDQxNTkxNTEsImVtbCI6IjYyMjM3NmY4LTAwMDAtMjIyMi1kN2Y5LTA3MGZhOTU2ZTk2M0Bhbm9ueW1vdXMuaW52YWxpZCIsImF1dGgiOiJINHNJQUFBQUFBQUFBSXVPQlFBcHUwd05BZ0FBQUE9PSIsImlzcyI6IlN5bmVyaXNlIiwiYnBpIjo0OCwiY2xJZCI6NDMzMjMwMjg4LCJleHAiOjE1NTMwMDcxNTksImFwayI6IjVBRUFBM0Q1LUUxNDctQzdFQi1ENTlFLUJDRjUwMTA5QTNEMSJ9.QOmSqrneR4mJFv4JdxTYsw_wGcDawDsVQuB-GVTcPPwijiP7lQ_Jzqq2Mypg1BS6WFlfGB8fzqCY9iMF_TdtjmoB4xBrY95ylU8L9qto-9Cw5x5TURkfxq31eryiHe2IteRAEtoVzYg2_s9QhlH6ANVcFOVp8dMno0V9bfMYfeSQa3FkjEbxFsseHkMOiADmp9-tOGtLXO942Ir-2W_Hz3Utlpt4erz0dVJBw8a-mFavPA8EEDWR7ACJNocrVHFkS3wFISh3LqLn6KkXiowaynKlJOEHGctuahzKmF3ZOJ1BvGgKohxF9OXvQs9IdmCfWhYsLr5Q2p04TJJ-MyvTipuggKVioh8mHmOFdfnN-Zused6tXzhZtKPUWTmM8cBKoAOBHExxcMQ8SVSjxnw_7_eLKm7S2wNpu0V-tiPZPCH4wYZXtWBYjmfy0V9ydjXnNunXfgxKixLeFNnONUXxEuqPLvM_xAuonQBXVN4nYrgJv8p8U6_ZlGMPjJq1szfcuBZnzI34LSEWx_nSof0XC5Czm8iG_ihG8naivNWS8h-Q-qKMP_3PPFsLSH4Egh03pH93EJUuNAeSO4RGfUX1wzMvrv1nBC1SM660uFMbq-wkplFBbKnHKMYe-qRs1-lZPG5PwPWJJdpGqOUzbnoMOJYmiq06OHHVQyJSkcEHLCk"
}

Refresh a Client token

Retrieve a refreshed JWT Token to prolong the Client session.

The current token must still be active at the time of the request.

  • API consumers who can use this method: Client (customer), anonymous Client
  • This method does not require a Synerise authorization token.
Authorizations:
Request Body schema: application/json
apiKey
required
string

Client API key

Responses

200

New authorization token

401

Unauthorized

post /v2/auth/refresh/client
https://api.synerise.com/sauth/v2/auth/refresh/client

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "apiKey": "string"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "token": "eyJhbGciOiinvalidI6IkFQSSIsInJsbSI6ImNsaWVudCIsImN0ZCI6MTUyODM1NTgzMjEzOCwiZW1sIjoia3J6eXN6dG9mLmN6ZXJlcGFrQGdtYWlsLmNvbSIsImlzcyI6IlN5bmVyaXNlIiwiYnBpIjo1OTQsImNsSWQiOjUyNTQ0NjU3NCwinvalidx2XwJp-QBZ94d_EEKf41KtDCE33KhP_vTAYrs-JzbnIHgKRvG6ZRwsNOL8OTnbfbUZH4XYaqBB_tZTPPKfzHutP6GEGp7PLtu2E92JbChkVyrn8VCQ5v4z2e1-zsdgbmWcQk2g9RydaydO6NYO55suT3Hz2ZRv0AYLsG8rM1biZGdREWx9OaknVVuIo2ivehBiukL7VQ6Bu8ugjep3mn-z666a-nCMh6ZuASiQ6Geq0NSWmdDQIoCa5Hg44KzMfGRlCR2uKBXeHTD0SkwJ1VJM0sHNKwSfMXKpaX8OJ5wUJpgCzDzQwKVgxgWFp4eO_sbcvxWrpI7W0lfdCy1WKirnZ6Uh3uJ06v97GQDAQqVgBZFEpS47MrGZhTNuAG4ZbfYO7yyxVO8AHQbEC-UvZ-8DC1XZjvQ6S1uNqQIlVGcthnrxg8K6vKVhNzu6ifQI0bbsCl8bGsKkXOEK1pKR3ekckcSjNeeY2LrcdXs8F2gtkm0TjXU"
}

Authenticate as Client

Obtain a new JWT token for a Client. If an account for the Client does not exist and the identityProvider is different than SYNERISE, this request creates an account.

  • This method does not require a Synerise authorization token.
Request Body schema: application/json
apiKey
required
string

Client API key

identityProvider
required
string
Enum: "SYNERISE" "FACEBOOK" "OAUTH" "APPLE" "GOOGLE" "UNKNOWN"

The identity provider.

identityProviderToken
string

Third-party authentication token used to authenticate with the Identity Provider. Required if identityProvider is different than SYNERISE.

email
string

Client email. Required if identityProvider is SYNERISE and email is the unique identifier (default setting).

customId
any

Client customId. Required if identityProvider is SYNERISE and customId is the unique identifier (see https://help.synerise.com/docs/settings/configuration/non-unique-emails/).

password
string

Client password. Required if identityProvider is SYNERISE.

uuid
string

Client UUID. Required if identityProvider is SYNERISE.

deviceId
string

Unique Android or iOS device ID

agreements
object

This object contains the marketing agreements of the Client.

You can also pass the values as strings ("true";"TRUE";"True"/"false";"FALSE";"False") or integers (1 for true and 0 for false).

attributes
object

This object contains custom attributes (with any names).

WARNING: Some attributes are reserved and cannot be sent. If you send them, they are ignored.

Click to expand the list of reserved attributes email
clientId
phone
customId
uuid
firstName
lastName
displayName
company
address
city
province
zipCode
countryCode
birthDate
sex
avatarUrl
anonymous
agreements
tags
businessProfileId
time
ip
source
newsletter_agreement
custom_identify
firstname
lastname
created
updated
last_activity_date
birthdate
external_avatar_url
displayname
receive_smses
receive_push_messages
receive_webpush_messages
receive_btooth_messages
receive_rfid_messages
receive_wifi_messages
confirmation_hash
ownerId
zipCode
anonymous_type
country_id
geo_loc_city
geo_loc_country
geo_loc_as
geo_loc_country_code
geo_loc_isp
geo_loc_lat
geo_loc_lon
geo_loc_org
geo_loc_query
geo_loc_region
geo_loc_region_name
geo_loc_status
geo_loc_timezone
geo_loc_zip
club_card_id
type
confirmed
facebookId
status
tags
Array of strings

Tags can be used to group Client accounts.

Responses

200

Client authorization token

400

Request failed, see error message for details

401

Unauthorized.

403

Authentication failed, see error message for details

404

Client not found

406

Account is locked, password reset required

423

Device control is enabled, device must be authorized (link sent by email)

post /v2/auth/login/client
https://api.synerise.com/sauth/v2/auth/login/client

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "apiKey": "string",
  • "identityProvider": "SYNERISE",
  • "identityProviderToken": "string",
  • "email": "string",
  • "customId": null,
  • "password": "string",
  • "uuid": "string",
  • "deviceId": "string",
  • "agreements":
    {
    },
  • "attributes":
    {
    },
  • "tags":
    [
    ]
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "token": "eyJhbGciOiJSUzUxMiJ9.eyJzdinvalidwYmZkM2FkNDg2ZjQ3ZGRiMjE5MSIsImF1ZCI6IkFQSSIsInJsbSI6ImFub255bW91c19jbGllbnQiLCJjdGQiOjE1NTMwMDQxNTkxNTEsImVtbCI6IjYyMjM3NmY4LTAwMDAtMjIyMi1kN2Y5LTA3MGZhOTU2ZTk2M0Bhbm9ueW1vdXMuaW52YWxpZCIsImF1dGgiOiJINHNJQUFBQUFBQUFBSXVPQlFBcHUwd05BZ0FBQUE9PSIsImlzcyI6IlN5bmVyaXNlIiwiYnBpIjo0OCwiY2xJZCI6NDMzMjMwMjg4LCJleHAiOjE1NTMwMDcxNTksImFwayI6IjVBRUFBM0Q1LUUxNDctQzdFQi1ENTlFLUJDRjUwMTA5QTNEMSJ9.QOmSqrneR4mJFv4JdxTYsw_wGcDawDsVQuB-GVTcPPwijiP7lQ_Jzqq2Mypg1BS6WFlfGB8fzqCY9iMF_TdtjmoB4xBrY95ylU8L9qto-9Cw5x5TURkfxq31eryiHe2IteRAEtoVzYg2_s9QhlH6ANVcFOVp8dMno0V9bfMYfeSQa3FkjEbxFsseHkMOiADmp9-tOGtLXO942Ir-2W_Hz3Utlpt4erz0dVJBw8a-mFavPA8EEDWR7ACJNocrVHFkS3wFISh3LqLn6KkXiowaynKlJOEHGctuahzKmF3ZOJ1BvGgKohxF9OXvQs9IdmCfWhYsLr5Q2p04TJJ-MyvTipuggKVioh8mHmOFdfnN-Zused6tXzhZtKPUWTmM8cBKoAOBHExxcMQ8SVSjxnw_7_eLKm7S2wNpu0V-tiPZPCH4wYZXtWBYjmfy0V9ydjXnNunXfgxKixLeFNnONUXxEuqPLvM_xAuonQBXVN4nYrgJv8p8U6_ZlGMPjJq1szfcuBZnzI34LSEWx_nSof0XC5Czm8iG_ihG8naivNWS8h-Q-qKMP_3PPFsLSH4Egh03pH93EJUuNAeSO4RGfUX1wzMvrv1nBC1SM660uFMbq-wkplFBbKnHKMYe-qRs1-lZPG5PwPWJJdpGqOUzbnoMOJYmiq06OHHVQyJSkcEHLCk"
}

Authenticate as Client (conditional)

Obtain a new JWT token for a Client.

  • If the account does not exist, an account is not created.
  • If any additional conditions are required for logging in, the response is HTTP200 and lists the conditions.
  • Note that using this endpoint requires authenticating as an anonymous Client first.
  • API consumer who can use this method: anonymous Client
  • Permission required: SAUTH_CONDITIONAL_AUTHORIZATION_CREATE
Authorizations:
Request Body schema: application/json
apiKey
required