Selz uses OAuth 2 for API authentication and authorization. Calls done in behalf of the user require the access token.

Authenticate your account when using the API by including your secret Access Token in the request. You can manage your Access Token in the developer settings of Selz. Your Access Token carry many privileges, so be sure to keep them secret!

User Authentication

This type uses an access token for a specific user and app pair, in order to operate on that user's account, to the extent allowed by that app's permission.

Example:

curl --request GET \
  --url 'https://api.selz.com/customers?limit=10' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR ACCESS TOKEN HERE'

OAuth 2

1. Get user authorization

To start an Authorization Code flow, your application should first send the user to the authorization URL:

https://api.selz.com/oauth/connect/authorize?
    response_type=code&
    client_id=YOUR_CLIENT_ID&
    redirect_uri=https://YOUR_APP&
    scope=SCOPES&
    state=RANDOM_UNIQUE_VALUE

Where:

  • response_type: response type should be code, indicating that we are using the authorization code grant flow.

  • client_id: the client ID of your Selz application, this can be found under Client Credentials in your Selz Dashboard > Settings > Developer > Apps.

  • redirect_uri: the URL to which Selz will redirect the browser after authorization has been granted by the user. The Authorization Code will be available in the code URL parameter. This URL must match exactly the Callback URL you specified when you creating your Selz application.

  • scope: the scopes which you want to request authorization for. Required scopes are: apibasic, apireadwrite and openid. Include offlineaccess_ to get a Refresh Token.

  • state (optional/recommended): an arbitrary alphanumeric value included in the request that is also returned in the token response. A randomly generated unique value is typically used for preventing cross-site request forgery attacks. The state can also be used to encode information about the user's state in the app before the authentication request occurred, such as the page or view they were on.

2. Log in / sign up

A new page will open where user must log in with his Selz details or sign-up if using Selz for the first time, and consent the permissions requested.

3. Get the authorization code

After a login/signup, an authorization code is generated and appended to the redirected URI, e.g.

https://YOUR_APP/?code=[CODE]

4. Get the token

Now that you have an Authorization Code, you must exchange it for an Access Token that can be used to call the API. Using the Authorization Code [CODE] from the previous step, you will need to POST to the Token URL:

curl --request POST \
  --url 'https://api.selz.com/oauth/connect/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=authorization_code' \
  --data 'client_id=YOUR_CLIENT_ID' \
  --data 'client_secret=YOUR_CLIENT_SECRET' \
  --data 'redirect_uri=https://YOUR_APP' \
  --data 'code=CODE'

Where:

  • grant_type: grant type should be authorizationcode_.

  • client_id: the client ID of your Selz application, this can be found under Client Credentials in your Selz Dashboard > Settings > Developer > Apps.

  • client_secret: the client Secret of your Selz application, this can be found under Client Credentials in your Selz Dashboard > Settings > Developer > Apps.

  • redirect_uri: the redirect URL must match exactly the redirect*uri passed to */authorize_ endpoint.

  • code: the Authorization Code received from the initial authorize request.

Your request will be followed by a response that includes access token and a refresh token:

{
    "access_token": "89db47bd3e9436418d3adea206475959e054c30adda8426a7804cc",
    "expires_in": 7776000,
    "token_type": "Bearer",
    "refresh_token": "560c067fddc4a82f23c03c03f37487edba5a2ebf8c14391b98c4e",
    "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IkFmS3BISFZNa3Q3RUQwQ0FtRWhibmhFRy1TNDY5WWVXYz"
}

All set! Your token is now ready to use. Add your access token in the request header for the endpoints that require it (see example with each request).

5. Swapping a token

In order to maintain uninterrupted connection, you can request a new access token whenever it is close to expiring. You can do this by doing a POST request to the Token endpoint using refreshtoken_ grant_type and passing the refresh token as shown below:

curl --request POST \
  --url 'https://api.selz.com/oauth/connect/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=refresh_token' \
  --data 'client_id=YOUR_CLIENT_ID' \
  --data 'client_secret=YOUR_CLIENT_SECRET' \
  --data 'refresh_token=YOUR_REFRESH_TOKEN'

The response will include your new access token:

{
    "access_token": "39f25a329de7d9c50bb4b2b63dd27e42020809fa9401b69a7161c",
    "expires_in": 7776000,
    "token_type": "Bearer",
    "refresh_token": "7566f47d7622c2bd528dedde7cabccf73e560ed362ee168800c39",
    "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IkFmS3BISFZNa3Q3RUQwQ0FtRWhibmhFRy1TNDY5WWVXYz"
}