Synerise uses a number of authentication methods in the API. The available methods depend on the endpoint and the consumer. JSON Web Tokens (JWTs) are the most common. ## API consumer types Synerise defines different types of API consumers that can receive their own authorization tokens. Each method within our API Reference indicates which types of API Consumers can use them. ### Profile This is the end user of your website or application - the one who browses pages, purchases items, and so on. In the portal, this is called a profile. In our APIs, the profile is usually called a "client" in endpoint URLs and JSON entity names. The profile can register and maintain their own account with following methods: - Synerise RaaS - Facebook authentication - OAuth-based authorization - Sign in with Apple They can also perform other customer actions, such as redeeming vouchers.
The profile can access and modify only its own data.
### Workspace The workspace is assigned to a particular company as explained [in these articles](/docs/settings/business-profile). This consumer can use methods that, for example, create profiles, record profile actions, or manage promotions. When working with the API, you will usually authorize as the workspace. ### User This is the user who logs in to [the Synerise Portal](https://app.synerise.com/). A User is an actual person who performs actions in the Synerise Portal interface, but many of those actions can be automated using the API. Users have access to *Workspaces* or *Organizations* and different levels of permissions within those.
Workspaces used to be called _business profiles_. Many endpoints still use this nomenclature due to backwards compatibility.
## Access control ### Access permissions Each endpoint requires a permission to access it. These permissions can be defined granularly for users, roles, or API keys, so you have strict control over access to each endpoint. You can also assign groups of permissions. To find which permission is needed for an endpoint, read the endpoint's description in the [API Reference](https://developers.synerise.com/). For more information on managing permissions, read [this article](/docs/settings/identity-access-management/permissions). ### IP allowlisting You can limit access to Synerise to certain IP addresses. For more information, see [IP access control](/developers/api/api-authorization/ip-access). ## JSON Web Tokens Authentication with [JSON Web Tokens (JWTs)](https://jwt.io/) is available in most of the API endpoints. The token is generated by one of the `/auth/login/` endpoints depending on the **Consumer Type**, as described further in this article. You need to include the received token in the `Authorization` header of your requests, with a `Bearer` prefix. See this simplified example of a call: ``` curl -X GET https://{SYNERISE_API_BASE_PATH}/v4/clients \ -H 'Accept: application/json' \ -H 'Api-Version: 4.4' \ -H 'Authorization: Bearer eyJhbGciOiJSzZXIiL...UFBQUFBSXVPQlFBcHUwd05BZ0FBQUE9PSIsIm5tZSI' \ -H 'Content-Type: application/json' ```
Remember to include a space between `Bearer` and the token.
If you are unauthorized or are using an invalid/expired token, the API returns `HTTP 401 Unauthorized` or `HTTP 403 Forbidden`. ### Token format Our JWT use the `RS512` hashing algorithm and their payload contains: - customer/user/profile identification. - the origin of the token (Synerise, Facebook, Oauth, Apple). - expiration time of the token. - **user tokens only:** information about the currently selected workspace and user permissions. ### Token lifetime By default, the token is valid for **one week**. You can request a refreshed token for the session by using the `/auth/refresh` endpoint **before** the current token expires. You can also verify your JWT signature by using the public key: - [Workspaces hosted on Microsoft Azure EU server](https://api.synerise.com/v4/public.pem) - [Workspaces hosted on Microsoft Azure USA server](https://api.azu.synerise.com/v4/public.pem) - [Workspaces hosted on Google Cloud Platform](https://api.geb.synerise.com/v4/public.pem)