API authentication

Sunshine Conversations' authentication scheme is distinct from Zendesk API tokens. This guide explains specifically how to authenticate requests against the Sunshine Conversations API.

Authentication methods

The Sunshine Conversations API supports two authentication types: basic authentication and bearer tokens (via JWT). While basic authentication is recommended in most cases, JWTs may still be useful in certain circumstances, for instance if you would like to add an expiry time to your credentials. Both authentication methods will require you to generate an API key in Admin Center.

For instructions on how to generate an API key, see app-scoped keys and integration-scoped keys in Zendesk help.

Access scopes

The table below summarizes the various scopes of access supported by the Sunshine Conversations API. Depending on your account type, some key types (and therefore some API endpoints) will be unavailable for use. Each endpoint in the API reference will specify the allowed access scopes, so make sure to use the right scope for your use case.

For basic authentication, the scope of access is determined automatically by the API key being supplied. When using JWT authentication, a scope claim must be added to the JWT payload which matches the scope of the API key being used.

Scope	Availability	Description
app	All account types	Provides access to all of the users and conversations created within an app, as well as app configuration details including integrations, webhooks, and the switchboard.
integration	All account types	Provides access to all of the users and conversations created within an app, but does not give access to create or manage other integrations or the app's switchboard. Integrations created via OAuth are granted a JWT with this scope.
user	All account types	Provides access to a single user’s conversation records, linked third party clients, and profile metadata. Can only be used as part of messaging authentication and is not accepted by the public API.
account	Sunshine Conversations direct accounts only	Provides access to all apps associated with a Sunshine Conversations direct account. Used in account provisioning use cases. Not applicable to Zendesk customers

Basic authentication

To authenticate using basic authentication, your key id should be supplied as the user name, and key secret as the password. The credentials are passed through the HTTP Authorization header. The content is Basic, followed by a space, followed by the base 64 of the string that contains the API key id and secret joined by :.

Pseudo code:

Authorization: Basic base64("{key_id}:{key_secret}")

Most languages will have HTTP libraries that provide convenience methods to avoid crafting the Authorization header manually. For example, when using curl, the --user option can be used:

curl https://{subdomain}.zendesk.com/sc/v2/apps/{app_id}/users/{user_id} \
     --user '{key_id}:{key_secret}'

JWT authentication

JWTs are an industry standard authentication method. A broad set of supported JWT libraries for a variety of languages and platforms are available.

A JWT is composed of a header, a payload, and a signature. The payload contains information called claims which describe the subject to whom the token was issued.

When to use JWTs

Basic authentication is the preferred method to authenticate requests to the API. However, JWTs are useful in certain cases.

Time-based expiration of credentials

If you want to generate credentials that expire after a certain amount of time, using JWTs is a good way to accomplish this.

The exp (expiration time) property of a JWT payload is honored by the Sunshine Conversations API. A request made with a JWT which has an exp that is in the past will be rejected. To accommodate clock skew, a 60 second grace period is allowed after JWT expiry.

Keep in mind that using JWTs with exp means that you will need to implement regeneration of JWTs, which demands additional logic in your software.

Example use cases:

• Temporarily sharing credentials for debugging purposes.
• Requiring integrations to rotate credentials by renewing them.

Sample JWT Structure with expiry

Header

{
  "alg": "HS256",
  "typ": "JWT",
  "kid": "{app_key_id}"
}

Payload

{
  "scope": "app",
  "exp": 1542499200 // unix timestamp
}

Authenticating users in SDKs

JWTs are required to identify your users with an external id in SDKs. In this case, JWTs are signed with a scope of user, and an additional payload property external_id. See messaging authentication for more information.

Signing a JWT

Step 1 - Obtain an API key

For instructions on how to generate an API key, see app-scoped keys and integration-scoped keys in Zendesk help.

Step 2 - Use the library available for your platform to create the JWT

Below are code samples for a few popular programming languages.

NodeJS:

Using the jsonwebtoken NPM module:

var jwt = require("jsonwebtoken")
var token = jwt.sign({ scope: "app" }, SECRET, { header: { kid: KEY_ID } })

Ruby:

Using the ruby-jwt gem:

require 'jwt'

payload = {:scope => 'app'}
jwtHeader = {:kid => KEY_ID}

token = JWT.encode payload, SECRET, 'HS256', jwtHeader

Python:

Using the pyjwt module:

import jwt
token = jwt.encode({'scope': 'app'}, SECRET, algorithm='HS256', headers={'kid': KEY_ID})

Step 3 - Start using the Sunshine Conversations API

# Calling GET /users/:id using a jwt
curl https://{subdomain}.zendesk.com/sc/v2/apps/{app_id}/users/{user_id} \
     -H 'authorization: Bearer {your-jwt}'

Specifying the scope of access

The scope of access represents the authorization level of requests made with a specific JWT. The scope is specified in the payload when signing a JWT, and must match the type of key being used to sign the JWT.

For app-scoped keys:

Header

{
  "alg": "HS256",
  "typ": "JWT",
  "kid": "{app_key_id}"
}

Payload

{
  "scope": "app"
}

For integration-scoped keys:

Header

{
  "alg": "HS256",
  "typ": "JWT",
  "kid": "{integration_key_id}"
}

Payload

{
  "scope": "integration"
}

Secure credential handling

Credentials issued with app and integration scope are highly sensitive. They grant broad access to all users in your app. If these credentials were to be compromised, it could jeopardize the privacy and security of your users. Safeguard these credentials very carefully.

Serving credentials to a browser or mobile application

You should only use app and integration scoped credentials to make server-to-server API calls from a secure environment; they should never be served to a mobile app or a browser. As a result, CORS headers are not served by the v2 API. Attempting to invoke the public API from a browser will result in a same-origin policy browser error.

Serving user scoped JWTs to a browser or a mobile application, however, is a necessary part of authenticating users. When implementing your messaging authentication flow, ensure that the user has first proven their identity by some means (such as logging in to your website, or presenting a valid session cookie) before your service issues them a JWT.

Rotating credentials

Rotating credentials is sometimes desirable in cases of a breach or as a regular rotation process (for example, yearly). To facilitate key rotation, you can create multiple API keys associated with your app or integration, which can all be used in parallel.

Deleting an API key will invalidate all JWTs signed with that API key and will cause all requests using basic authentication with that API key to be refused. To avoid downtime during a key rotation, make sure that your new key is successfully deployed to all relevant services before revoking the old one.