Submit a request

Articles in this section

Chime API + OAuth 2.0

Avatar
ITS Helpdesk
Updated
Follow

Summary

 

 

Chime API

"API" stands for "Application Programming Interface." An API is a software that allows two applications to connect to each other. Chime has an "Open API" meaning users and/or vendors can access available endpoints as long as they have account credentials to do so.

 

Accessing Chime's API

To access Chime's API, please see https://api.chime.me/docs/index.html.

 

(1) API Key

If you are integrating another application with Chime and it asks for your Chime API key, here is where you can find that. Navigate to Settings > Integrations > API:
API_page.jpeg

 

(2) Developer Access

If you are a developer and you are looking to build an API connection with Chime, please review the details in Chime OAuth 2.0.

 

Email Address Verification

As of July 5, 2021, leads that are brought into Chime via our API will now have their email address checked with a third-party vendor to determine if it is valid or not. If an email address is found to be invalid, it will be marked as such within a lead profile page and this keeps auto-emails from being sent to that address.

profile_page_.jpeg


Chime OAuth 2.0

OAuth 2.0 is an open standard for account access authorization without requiring passwords to be provided to third parties. This method provides developers with a secure way to access Chime API data on behalf of Chime platform users. Most commonly, OAuth 2.0 authentication is useful to set up integrations between third-party applications (referred to as "vendors") and Chime.

For reference, here is Chime's API https://api.chime.me/docs/index.html

 

 

Create a Developer Account

First, access the Chime Developer Platform. 

 

To create a developer account, click on the Sign Up link:

mceclip0.png

 

Provide all of the required information and then click Sign Up:

mceclip2.png

 

Your credentials should be auto-generated so you can click on the login button to access your new developer account:

mceclip0.jpg

 

Register an Application

*Note: You can repeat this process multiple times if you have multiple applications that you are connecting with Chime.

 

Once logged into your developer account, you will be presented with your authorizations dashboard:

mceclip1.png

 

To start a new application click on the + Add More Authorizations button:

mceclip2.png

 

Provide all of the required information and then click on the Submit button to send in the application.

  • App Name
  • Website
  • Authorized Redirect URL
    • The "Authorized" or "Denied" status will also be returned in this URL
  • Description
  • App Logo
  • Primary Contact Name
  • Primary Email
  • Primary Phone Number

mceclip3.png

 

Once you hit submit, your application will be listed on its own line within the authorizations dashboard along with the following columns:

  • App 
  • Website
  • Authorized Redirect URL
  • Client ID
  • Client Secret
  • Description
  • Primary Contact Info
  • Status
    • All
    • Under Review
    • Approved
    • Rejected

*IMPORTANT: If at any time you need to update your application details, please reach out to the Chime Support Team (support@chimeinc.com) and they will work on doing so manually.

 

Review Process/Results

After submitting your application, you will be able to monitor the status via the Chime Developer Platform. Simply log in and access your authorization dashboard and review the Status column at the far right.

 

Under Review

This status will display until the application is reviewed and either approved or rejected. This process should only take around three business days. If you do not receive a response before then, please send an email to Chime Support (support@chimeinc.com). 

mceclip5.jpg

 

Rejected

If rejected, the primary contact submitted with the application will receive an email with more details on why it was rejected. You can then click the Resubmit button to edit the information provided before submitting again.

mceclip6.png

 

Approved

If approved, you will see the client_id and client_secret in your account. You will need this information for the next step.

client_id
client_secret

mceclip8.jpg

 

OAuth 2.0 Implementation

In this section, we will discuss setting up OAuth 2.0 to authenticate users of your app and then demonstrate how to make a call to Chime's API using the Access Token. This diagram is provided as a visual representation of this process:

mceclip9.jpg

 

User Authentication

Before your application can access private data using Chime's API, it must obtain an Access Token that grants access. There are several ways to make this authorization request, for example, a JavaScript application might request an access token using a browser redirect to Chime.
Once redirected to Chime, the user needs to log into their Chime account. After logging in, the user is asked whether they are willing to grant the permission that their application is requesting. This process is called user consent.

Your server doesn't need to do anything at this stage except wait for a response from the Chime server to indicate whether the access is granted or not.

 

HTTP

https://chime.me/page/vendor-auth.html?clientId=${clientId}

 

Parameter Description

Column
Type
Description
client_id
String
Determine which client is making the request. The parameter value passed must be exactly the same as the one displayed in the Developer Platform.

 

The Chime server will send the response to the Authorized Redirect URL you submit in your application. The Auth_Code or error message that is returned to your server appears on the query string, as shown below:

 

Auth_Code Response

If the user grants permission, the Chime Server will send the Auth_Code to the Authorized Redirect URL.

 

HTTP

⁣https://oauth2.example.com/auth?code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7⁣

 

Error Response

If the user does not grant permission, the server returns an error.

 

HTTP

https://oauth2.example.com/auth?error=access_denied

 

Using Auth_Code to get Access Token and Refresh Token

After your application server receives the Auth_Code, you can use it to exchange the Access Token and Refresh Token.

You can then use the Access Token to call Chime's API on behalf of the user.

 

HTTP

⁣POST api/user-web/oauth/token HTTP/1.1
Host: chime.me
Content-Type: application/x-www-form-urlencoded
Headers:
Authorization:Basic atughMaQm6bTrgtp7bas=

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=&
redirect_uri=https%3A//oauth2.example.com/code&
grant_type=authorization_code

 

Parameter Description

Column
Type
Description
client_id
String
The client ID obtained from the Vendor Credentials page.
code
String
The authorization code returned from the initial request.
grant_type
String
As defined in the OAuth 2.0 specification, this field's value must be set to authorization_code.
redirect_uri
String
One of the redirect URIs listed for your project in the Vendor Credentials page for the given client_id.
Authorization
String
Basic Auth, Base64 of "{clientId}:{clientSecret}"

 

The following is the description of the returned fields:

Column
Type
Description
access_token
String
The token that your application sends to authorize a Chime API request.
expires_in
int
The remaining lifetime of the access token is in seconds.
refresh_token
String
A token that you can use to obtain a new access token. Refresh tokens are valid until the user revokes access or created more than 180 days.
token_type
String
The type of token returned. At this time, this field's value is always set to Bearer.
scope
String
Currently a fixed value， "openApi"

 

Refreshing Access Token

Access tokens periodically expire and become invalid. You can use the Refresh Token to refresh and obtain a new Access Token without prompting the user for permission

 

HTTP

⁣POST api/user-web/oauth/token HTTP/1.1
Host: chime.me
Content-Type: application/x-www-form-urlencoded
Headers:
Authorization:Basic atughMaQm6bTrgtp7bas= 

refresh_token={your refresh_token}&
grant_type=refresh_token

 

Parameter Description

Column
Type
Description
client_id
String
The client ID was obtained from the Vendor Credentials page.
code
String
The authorization code returned from the initial request.
grant_type
String
As defined in the OAuth 2.0 specification, this field's value must be set to refresh_token.
redirect_uri
String
One of the redirect URIs listed for your project in the Vendor Credentials page for the given client_id.
Authorization
String
Basic Auth, Base64 of "{clientId}:{clientSecret}"

 

The following is the description of the returned fields:

Column
Type
Description
access_token
String
The token that your application sends to authorize a Chime API request.
expires_in
int
The remaining lifetime of the access token in seconds.
refresh_token
String
A token that you can use to obtain a new access token. Refresh tokens are valid until the user revokes access or created more than 180 days.
token_type
String
The type of token returned. At this time, this field's value is always set to Bearer.
scope
String
Currently a fixed value， "openApi"

 

Chime User Experience

As a sample of what the user experience would look like if this was configured, please reference Managing Authorization by Third-Party Apps & Services.

 

 

Questions?

If you have any questions regarding this topic or any others, please reach out to our Support Team via email at <support@chimeinc.com>, by phone at 1 (855) 981-7557, or by a chat with us through your Chime CRM. 

 

Related terms: Open API, Developer Platform

 

Was this article helpful?
0 out of 0 found this helpful
Chime API + OAuth 2.0

Related articles

Comments

0 comments

Article is closed for comments.

All Rights Reserved.

Contact Us: support@chimeinc.com | 8:00 AM - 8:00 PM EST, Mon - Sun