OAuth Authentication

Capture RESTful api calls normally use client credentials to authenticate with Capture, allowing the API to complete the call.  This method uses the client_secret and client_id  as parameters in the call.

However, the entity, entity.create, entity.update, entity.replace, and entity.delete API calls may alternatively use the OAuth authentication method. Using this method, the client_secret and client_id are exchanged for a code or a token. This token is then used as a parameter in the RESTful call.

Two Token Types ¶

• access_token — used to access existing records. Use with entity, entity.update, entity.replace, and entity.delete.  The oauth/token call acquires this token.
• creation_token — used to create new records. Use with entity.create. The access/getCreationToken call acquires this token.

Warning: For security’s sake, never send the client secret over an unsecure connection or use it in a browser. There are exploits for gathering sensitive information via email, instant messaging, or even ticket tracking systems. Once the client secret is compromised, your user data is at risk.

How to use Oauth Authentication to retrieve an access_token

1. Determine the redirect_uri for the token will be delivered. This path should lead to a page that has the ability to capture the token.
2. Define the type_name, and use a record_selector to determine any entities that access will be granted to.
3. Use these values to make an access/getAuthorizationCode call.
4. The authorization code is then returned to the redirect_uri. Use this code to make an oauth/token call.
5. The access_token is returned to the redirect_uri specified in the oauth/token call (Note: this may be different than the one used to retrieve the access_code.)

How to retrieve a creation_token

1. Define the type_name, and the amount of time the token will be valid.
2. Use these values to make an access/getCreationCode call.
3. The authorization code is then returned directly by the call in the JSON response. Use this code to make an entity.create call without using the client_secret/client_id combo.