Environment Headers and Authentication

Common headers or authentication settings can be configured in an environment and applied to all requests within a test. When specified, default headers and auth settings will be automatically included in each request step for your test. Variables can be used, but will only be evaluated at the beginning of the test run, before the first step is executed.

• Default Headers
• Default Authentication
• Client Certificates
  • Upload Certificate Files
  • Add Certificate Contents via Text

Default Headers

Default headers are useful for specifying header values like user agents, content types, and OAuth 2.0 bearer tokens that apply to all requests within a test. If a header is specified in an environment but also a request, the request-specific value will take precedence when the test is executed. This setting is also inherited from a parent environment if specified, but can be overridden on a per-test basis.

Default Authentication

You can add a default authentication method to be used for each test or request step. API Monitoring supports Basic authentication, OAuth 1.0, OAuth 2.0, and authentication using your local client certificate.

To add a default authentication:

1. In API Monitoring, create a new test or select one of your existing tests.
2. From the menu on the left, select Editor.
3. Expand Test Settings.
4. Click Authentication.
5. Select your chosen method under Authentication Methods.

To switch to another type of authentication, select Clear Default Authentication.

Add Basic Auth

Set a user name and password credential that will be added as an Authorization header, and will be included in all requests in the test.

Add OAuth 1.0

To set up OAuth 1.0, provide the following information:

• Consumer Key: The Consumer Key used for asking the service for authorization.

• Consumer Secret: The Consumer Secret used for asking the service for authorization.

• Access Token: The token used for accessing the resource.

• Token Secret: The secret that accompanies the access token.

• Signature Type: Choose to insert the signature type in Authorization header, Querystring, or Body.

The required signature will be automatically generated using these credentials and included in all requests in the test.

Add OAuth 2.0

To set up OAuth 2.0 authentication:

1. Provide access token. If none is available, create a new token.

2. Choose to add the authorization to Authorization header or Request URL.

3. (Optional) Enable the Auto-Refresh Token toggle to automatically replace expired tokens with new ones.

The required signature will be automatically generated using these credentials and included in all requests in this test. Once generated, you can also copy the token and its attributes.

To create a new token, use the Create new token form:

• Grant Type: Choose your grant type according to your test requirement.

  If the Client or Application...	Choose this Grant Type:
  Is itself the Resource Owner (User), and you need an Application-to-Application interaction	Client Credentials
  Is a web app executing on a server	Authorization Code
  Is a single page app (JavaScript app)	Authorization code with PKCE or Implicit
  Is trusted with User credentials	Password Credentials
  Is a Native or Mobile app	Authorization code with PKCE

  For Authorization Code, Authorization Code with PKCE, and Implicit grant types, you must add or register the API Monitoring Redirect URI, https://www.runscope.com/oauth2/callback, to the third-party authorization site. See Redirect URI Registration for details.

• Auth URL: Enter the third-party authorization URL.

• Access Token URL: Enter the URL for generating the access token.

• Client ID: Enter client ID.

• Client Secret: Enter client secret.

• Code Challenge Method: (PKCE only) Choose between SHA-256 or Plain.

• Code Verifier: (PKCE only) Enter the code verifier string generated by the app, if available.

• Username: (Password Credentials only) Enter the user name for authorization.

• Password: (Password Credentials only) Enter the password for authorization.

• Scope: Add the scope string, if one is used.

• State: Add the state string, if one is used.

• Client Authentication: Send as Basic Auth header, or as client credentials in the body.

• Select Get Access Token.

Add Client Certificate

Select this option to use your local client certificates for authentication.

Client Certificates

Custom client certificates can be stored to be used by requests within a test.

You can create:

• A PEM-encoded, password protected certificate file that you upload. See Upload Certificate Files.
• A PEM-formatted, non password protected certificate that you paste into the text area. See Add Certificate Contents via Text.

Client Certificate support requires a qualifying plan. Contact sales to get started.

Upload Certificate Files

We support password-protected encrypted client certificates with the following specifics:

• A PEM-encoded certificate file. The max file size is 1 MB.
• A PEM private key file for the certificate (optional). The max file size is 1 MB.
• A Passphrase for the certificate (optional). The max length is 128 characters.
  For an even higher level of security, you can use a Team Secret or a Bucket Secret for the Passphrase.

Follow these steps:

1. In API Monitoring, select one of your existing tests.
2. From the menu on the left, select Editor.
3. Expand Test Settings.
4. Click Authentication.
5. In the Client Certificates section, select Upload File.
   
6. Upload a certificate file. Click Choose File.
   The max file size is 1 MB.
7. (Optional) Upload a key file. Click Choose File.
   The max file size is 1 MB.

   If you choose to upload a key file, your certificate has to be already uploaded.

8. (Optional) Enter a passphrase.
   If you choose to enter a passphrase, your certificate and key have to be already uploaded.
9. Click Upload Certificate.

You are now able to add the certificate to requests in your test by selecting Add Client Certificate under the Authentication options of an individual request or environment.

To delete the certificate, go to Test Settings, Authentication, Client Certificates section and click the delete icon. The certificate, key and passphrase will be deleted. Clear authentication by clicking Clear Default Authentication under Authentication Methods, if enabled.

Add Certificate Contents via Text

The text needs to be a PEM-formatted certificate which has the CERTIFICATE section, and PRIVATE KEY, both are required.

Follow these steps:

1. In API Monitoring, select one of your existing tests.
2. From the menu on the left, select Editor.
3. Expand Test Settings.
4. Click Authentication.
5. In the Client Certificates section, select Add Certificates Via Text.
   
6. Copy and paste the contents of a certificate.
   

   Example:

   -----BEGIN CERTIFICATE-----CERTIFICATETXTCOMESHERE-----END CERTIFICATE-----\n-----BEGIN PRIVATE KEY-----PRIVATEKEYCONTENTSCOMESHERE-----END PRIVATE KEY-----
7. Click Save.

Once saved, you will be able to add the certificate to requests in your test by selecting Add Client Certificate under the Authentication options of an individual request or environment.

To delete the certificate, go to Test Settings, Authentication, Client Certificates section and delete the certificate from the text box. Clear authentication by clicking Clear Default Authentication under Authentication Methods, if enabled.