Authentication

This article introduces the authentication mechanisms supported by Zuora.

OAuth v2.0

Zuora recommends that you use OAuth v2.0 to authenticate to the Zuora REST API.

Zuora recommends you to create a dedicated API user with API write access on a tenant when authenticating via OAuth, and then create an OAuth client for this user. See Create an API User for how to do this. By creating a dedicated API user, you can control permissions of the API user without affecting other non-API users.

If a user is deactivated, all of the user's OAuth clients will be automatically deactivated.

Authenticating via OAuth requires the following steps:

  1. Create a client
  2. Generate a token
  3. Make authenticated requests

Create a client

You must first create an OAuth client in the Zuora UI. To do this, you must be an administrator of your Zuora tenant. This is a one-time operation. You will be provided with a Client ID and a Client Secret. Please note this information down, as it will be required for the next step.

Note: The OAuth client will be owned by a Zuora user account. If you want to perform PUT, POST, or DELETE operations using the OAuth client, the owner of the OAuth client must have a Platform role that includes the "API Write Access" permission.

Generate a Token

After creating a client, you must make a call to obtain a bearer token using the Create an OAuth token operation. This operation requires the following parameters:

  • client_id - the Client ID displayed when you created the OAuth client in the previous step
  • client_secret - the Client Secret displayed when you created the OAuth client in the previous step
  • grant_type - must be set to client_credentials

Note: The Client ID and Client Secret mentioned above were displayed when you created the OAuth Client in the prior step. The Create an OAuth token response specifies how long the bearer token is valid for. You should reuse the bearer token until it is expired. When the token is expired, call Create an OAuth token again to generate a new one.

Make Authenticated Requests

To authenticate subsequent API requests, you must provide a valid bearer token in an HTTP header:

Authorization: Bearer {bearer_token}

If you have the Multi-entity feature enabled, you need to set an additional header to specify the ID of the entity that you want to access. You can use the scope field in the Create an OAuth token response to determine whether you need to specify an entity ID.

If the scope field contains more than one entity ID, you must specify the ID of the entity that you want to access. For example, if the scope field contains entity.1a2b7a37-3e7d-4cb3-b0e2-883de9e766cc and entity.c92ed977-510c-4c48-9b51-8d5e848671e9, specify one of the following headers:

  • Zuora-Entity-Ids: 1a2b7a37-3e7d-4cb3-b0e2-883de9e766cc
  • Zuora-Entity-Ids: c92ed977-510c-4c48-9b51-8d5e848671e9

Note: For a limited period of time, Zuora will accept the entityId header as an alternative to the Zuora-Entity-Ids header. If you choose to set the entityId header, you must remove all "-" characters from the entity ID in the scope field.

If the scope field contains a single entity ID, you do not need to specify an entity ID.

Other Supported Authentication Schemes

Zuora continues to support the following additional legacy means of authentication:

  • Use username and password. Include authentication with each request in the header:
    • apiAccessKeyId
    • apiSecretAccessKey

    Zuora recommends that you create an API user specifically for making API calls. See Create an API User for more information.

  • Use an authorization cookie. The cookie authorizes the user to make calls to the REST API for the duration specified in Administration > Security Policies > Session timeout . The cookie expiration time is reset with this duration after every call to the REST API. To obtain a cookie, call the Connections resource with the following API user information:
    • ID
    • Password
  • For CORS-enabled APIs only: Include a 'single-use' token in the request header, which re-authenticates the user with each request.

Entity Id and Entity Name

The entityId and entityName parameters are only used for Zuora Multi-entity. These are the legacy parameters that Zuora will only continue to support for a period of time. Zuora recommends you to use the Zuora-Entity-Ids parameter instead.

The entityId and entityName parameters specify the Id and the name of the entity that you want to access, respectively. Note that you must have permission to access the entity.

You can specify either the entityId or entityName parameter in the authentication to access and view an entity.

  • If both entityId and entityName are specified in the authentication, an error occurs.
  • If neither entityId nor entityName is specified in the authentication, you will log in to the entity in which your user account is created.

To get the entity Id and entity name, you can use the GET Entities REST call. For more information, see API User Authentication.

Token Authentication for CORS-Enabled APIs

The CORS mechanism enables REST API calls to Zuora to be made directly from your customer's browser, with all credit card and security information transmitted directly to Zuora. This minimizes your PCI compliance burden, allows you to implement advanced validation on your payment forms, and makes your payment forms look just like any other part of your website.

For security reasons, instead of using cookies, an API request via CORS uses tokens for authentication.

The token method of authentication is only designed for use with requests that must originate from your customer's browser; it should not be considered a replacement to the existing cookie authentication mechanism.

See Zuora CORS REST for details on how CORS works and how you can begin to implement customer calls to the Zuora REST APIs. See HMAC Signatures for details on the HMAC method that returns the authentication token.