Authentication

The Runscope API uses OAuth 2.0 for authentication. OAuth2 is a protocol that lets applications ask for authorization to a Runscope account without getting their password. Access tokens can be limited to specific types of data, and can be revoked by the user at any time.

Applications

To use the API, you must first create an Application.

Applications must have a name, website URL, and callback URL. Once you create an application you'll be given a Client ID and a Client Secret to use in the authorization flow.

When you create the application, we automatically authorize your own account for it and generate an access_token for your own use. This makes it easy to start using the API for personal use without building a web flow.

To build applications that access data on other Runscope Accounts, you will need to send users through the Web Application Flow.

Web Application Flow

Step 1: Redirect to Authorization Dialog

To begin the OAuth flow, redirect a user to the Authorize URL.

GEThttps://www.runscope.com/signin/oauth/authorize

Example Redirect

HTTP/1.1 302 Found 
Location: https://www.runscope.com/signin/oauth/authorize?client_id=XXXXXX
                                                         &redirect_uri=https://example.com
                                                         &response_type=code
                                                         &scope=api:read%20messsage:write
                                                         &state=random_value

Authorize URL Parameters

client_id required The Client ID of your application
redirect_uri required The Callback URL of your application. After authorizing your application a redirect will be made to this URL with an authorization code.
response_type required The desired grant type, as per the OAuth 2.0 spec. The only current valid value is response_type=code
scope   A space separated list of scopes. Valid scopes are listed below.
state   An unguessable random string. This state will be sent back to your application's Callback URL. It should be used to protect against cross-site request forgery attacks on your application.

Available Scopes

api:read Default read access. Allows you to see most of the user's account information including message streams and buckets. Authenticated buckets are not included and require the bucket:auth_token scope.

Since a bucket key is all you need to make requests, this permission allows you to create messages in the user's account by creating a Gateway URL from their bucket key. To create messages via the API directly, request the message:write scope.
bucket:auth_token Allows you to read all bucket information, including Authenticated Buckets.
bucket:write Allows you to create new buckets on behalf of the user (up to their plan limit).
message:write Allows you to create new messages on behalf of the user (up to their plan limit).
account:email Allows you to read the email addresses of user accounts.
team:read Allows you to read team details such as lists of team members and external service integrations.
test:read Allows you to read the details of API tests.
test:write Allows you to update and delete details of API tests.

The user will be presented with the following confirmation screen:

After clicking Authorize, they will be redirected to your Callback URL.

Step 2: We Request Your Callback URL

Once the app has been authorized, Runscope will redirect the user back to your Callback URL with an authorizaton code included in a code URL parameter. If the user declines to authorize your app, a redirect to your Callback URL will be issued with a error=access_denied URL parameter.

Sample Callback URL Request (Authorization Granted)

GEThttps://example.com/oauth_callback?code=38a6c89f-7c15-4c95-ab48-8b733849958b

Authorization Codes are only valid for a short time, you must exhange the code for an access token with 60 seconds or you will have to send the user through the authorization flow again.

Step 3: Exchange Code for Access Token

You may now use this code to retrieve an Access Token from the Access Token URL.

Request

POSThttps://www.runscope.com/signin/oauth/access_token

Parameters
client_idrequiredThe Client ID of the application.
client_secretrequiredThe Client Secret of the application.
coderequiredThe code you received in your Callback URL.
grant_typerequiredThe only valid value is authorization_code.
redirect_uri The Callback URL specified for this application.

Response

We will return a response with an access_token. This access token may be stored and used until the user revokes access to your application.

Sample Response Data
200 OK
Content-Type: application/json

{"access_token":"43541d4a-c4b0-43b1-bd26-33231e06b71d","token_type":"bearer"}

Whew! Now that you have an access token, it's time to start making API requests.