Authentication

To access your account via the API you'll need to create an API Key and API Secret Key for authentication.

Admin Users

To obtain an API Key and API Secret Key administrative users can go to  Security > API Access and click Create an API Key.

As API Keys are generated per user you will need to select the user for which you wish to generate keys. Make sure to generate keys per each user that accesses the API.

All API Keys for all users will then display on the API Settings page. If at any time you suspect that a user's API Key has been compromised, you can click the Regenerate API key button to create a new key.

What Happens if a User Tries to Authenticate with an Old Key?

If you create a new key for a user that has an existing key, their old API key is deleted and will no longer work. Here is the return you will get:

"result_ok": false,
"code": 401,
"message": "Login failed / Invalid auth token"

If you are simply creating a key for a new user this will not affect any of the other keys set up in your account.

Non-Admin Users

For non-admin users once your account administrator has generated a API Key for you this will be available under Account > Integrations > API Key. If you do not have an API Key here, contact your account administrator to generate one.

Making Calls with Your API Key

Here is an example call using an API key:

https://api.alchemer.com/v4/survey?api_token=E4F796932C2743FEBF150B421BE15EB9&api_token_secret=A9fGMkJ5pJF1k

Invalid api_token or api_token_secret

If you supply and invalid api_token or api_token_secret, you will see the following error message:

Invalid api_token or api_token_secret supplied

OAuth

To authenticate using OAuth, you'll want to first register your plug-in/application. Each plug-in application you register will be provisioned a consumer key and secret. This key and secret scheme are similar to the public and private keys used in protocols such as ssh for those who are familiar. This key and secret will be used, in conjunction with an OAuth library in your programming language of choice, to sign every request you make to the API. It is through this signing process that we trust that the traffic that identifies itself is you is, in fact, you.

Registering Your Application

Registering your application is simple. Simply log into your Alchemer account and fill out the OAuth Application Registration form. To get to the OAuth Application Registration form go to the below URL:

US Customers use:

https://app.alchemer.com/account/restful-register

EU Customers use:

https://app.alchemer.eu/account/restful-register

Canada Customers use:

https://app.alchemer-ca.com/account/restful-register

 Example Consumer Key and Consumer Secret after submitting OAuth Registration Form

OAuth 1.0 Authorization Flow

This is a typical OAuth 1.0 authorization flow, it may differ in your case. 

1. Call the Request Token service with your Consumer Key and Secret to get the Request Token. Set the callback URL to the URL that you control. 
2. Redirect your user to the login URL, including the Request Token. The user will login with their username and password and be redirected to your callback URL. That callback will include the OAuth 1.0 verifier that you need to get the Access Token.
3. Call the Access Token service with OAuth 1.0 verifier from the callback to get the Access Token and Token Secret.
4. Make API calls using OAuth 1.0 in that user's scope with the Consumer Key and Consumer Secret along with the Access Token and Token Secret. 

Request Token URL

User Authorization URL

Access Token URL