OAuth 2.0

Optimizely provides the OAuth 2.0 protocol to allow users to authorize third party applications to access Optimizely data via the REST API. It allows any Optimizely customer to grant access to an application without the need to share their Optimizely username and password. View and revoke applications you've authorized in your account settings.

To build an OAuth 2.0 flow in your application, you'll need to complete the following steps:

  • Decide which Grant Type is most appropriate for your application
  • Register your application with Optimizely
  • In your application, point customers to Optimizely's authorization URL
  • Process a redirect after the user accepts (or rejects) your application's access
  • Obtain an access token, via an authorization code or refresh token, or via the redirect itself, depending on the authorization flow you're using
  • Authenticate with the REST API using the provided access token

The following sections walk through each of these steps in detail.

If at any point you have any questions or need some help building out an OAuth 2.0 flow, you can ask the developer community, or you can submit a ticket to the developer support team. We'll be happy to help.


OAuth 2.0 flow

Grant types

As of August 2015, Optimizely supports both the Authorization Code and Implicit grant types, as described in the OAuth 2.0 spec. Read below for more information on the difference between these grant types and decide which is most appropriate for your application.

Authorization code grant

The authorization code grant is used to obtain both access tokens and refresh tokens and is optimized for confidential clients. It’s more versatile than the implicit grant and can give an application indefinite access to Optimizely on behalf of a user with a single authorization request. However, it is more complex to implement, and it requires the application to implement server-side code as well as a means of securely storing confidential information, including both a client secret and refresh tokens.

Read more about the Authorization Code Grant in the official OAuth 2.0 spec.

Implicit grant

The implicit grant type is optimized for public clients. Such clients will receive a valid access token at their redirection URL immediately after the user authorizes their application. Access tokens expire after 2 hours.

It is important to note that the implicit grant does not support refresh tokens. Therefore, any application using the implicit grant will need to explicitly re-request authorization from the user when an access token expires.

Read more about the Implicit Grant in the official OAuth 2.0 spec.

Registration

You must be an Administrator of an Optimizely account to register an application. Registering an application requires the following inputs:

  • An application name that identifies your application to Optimizely customers
  • One or more redirect URIs, that users will be redirected to after authorizing access to your application
  • A client type (either public or confidential) according to the grant type you wish to use in your application

Upon registering an application, you will receive a client ID that will uniquely identify your application and is required in the authorization flow described below. You will also receive a client secret which is required for an authorization code exchange.

To register a new application, follow the instructions on app.optimizely.com/accountsettings/apps/developers.

Authorization

To enable users to authorize your application, you must link to Optimizely's authorization endpoint on app.optimizely.com using the client ID and a redirect URI provided during registration. For example, the link shown on the right will send the user to an authorization flow for client ID 123 with a redirect to http://myapplication.com. See the table below for a full list of required parameters in the authorization endpoint.

We recommend you use the Connect with Optimizely button below, which you may resize as needed:


Download Button: PNG | SVG

After clicking this link, users will be prompted to log in to Optimizely if they aren't already. They will then be given the option to accept or deny authorization for your application. Users can revoke your application's access to their data at any time in their API Access settings.

Definitions

client_id

The client ID for your application (see app settings).

redirect_uri

A URL-encoded redirect URI to which the user will be redirected after successful (or failed) authorization. Must match one of the URIs provided during registration. If you are using an authorization code grant, insecure URLs such as those starting with http:// will be rejected. You can always add more redirect URIs to your application on the registration page.

response_type

The grant type your application requests for authorization. As of August 2015, the supported types are token (for implicit grant) and code (for authorization code grant).

scopes

A string denoting the access scope(s) your application requires after authorization. As of March 2015, the only supported value is all, meaning the generated token will have permissions that match the user role of the authorizing user.

state

A value you provide that will be relayed back to you in the response, to protect against CSRF attacks. For more information, see the CSRF section of the OAuth 2.0 spec.

account_id

(Optional) Specify the Account ID you want to authorize against.

Redirection

If the user accepts (or rejects) authorization, Optimizely will send an HTTP GET request to the redirect URI provided during authorization with the values described below.

If you are using the implicit grant flow, this information will be provided in the URL fragment. The examples on the right show redirects to http://myapplication.com in both cases where the user accepts and rejects authorization.

If you are using the authorization code flow, this information will be provided in the redirection query parameters. The examples on the right show redirects to http://myapplication.com in both cases where the user accepts and rejects authorization.

Definitions

access_token

Implicit grants only. If you are using the implicit grant flow, this key will contain a valid access token you can use to access the REST API on behalf of the authorizing user. Jump to Authentication for instructions on using an access token to access the REST API.

code

Authorization code grants only. If you are using the authorization code flow, this parameter contains an authorization code, which you can use to exchange for an access token and refresh token. The authorization code will expire in 10 minutes and can only be used once. Jump to Authorization Code for instructions on obtaining an access token.

token_type

Implicit grants only. As of March 2015, the only supported type is bearer.

state

The state you provided in the authorization request. You should verify this value matches the state you provided earlier.

expires_in

Implicit grants only. The TTL for this token in seconds. As of March 2015, all access tokens will expire in 2 hours (7200).

Authorization code

For authorization code grants only.

After you obtain an authorization code, you can exchange this authorization code for an access token by issuing an HTTPS POST request to Optimizely’s authorization server.

The code at right shows an example request and a successful response. The response will include an access token (with a lifetime of 2 hours) as well as a refresh token that can be used to request more access tokens after the initial access token expires.

Definitions

code

The authorization code returned in the redirect.

client_id

The client ID for your application (see app settings).

client_secret

The client secret for your application (see app settings).

redirect_uri

The redirect URI that was used when requesting the authorization code.

grant_type

As defined in the OAuth 2.0 spec, this field must contain a value of authorization_code.

Refresh tokens

For authorization code grants only.

After the authorization code exchange, you can exchange a refresh token for an access token by issuing an HTTPS POST request to Optimizely’s authorization server.

The code at right shows an example request and a successful response. In the event the user has revoked your access, you will receive an HTTP 403 response.

Definitions

refresh_token

The refresh token returned from the authorization code exchange.

client_id

The client ID for your application (see app settings).

client_secret

The client secret for your application (see app settings).

grant_type

As defined in the OAuth 2.0 spec, this field must contain a value of refresh_token.

Authentication

Using the access token provided in the authorization response, your application can now access the REST API on behalf of the authorizing user. You can use the REST API as outlined in this documentation, except you should use a header in the format Authorization: Bearer [token] instead of Token: [token], as shown in the example on the right.

Your application should check for 403 errors, in case the user has revoked application access or the token has expired. In such cases, to resume access you will need to prompt users to repeat the authorization flow.

Deletion

You can edit or delete your application at any time in your Optimizely account settings. You must have an Administrator role to perform these actions.

To delete a registered application, follow the instructions on optimizely.com/accountsettings/developer.