Upgrading Basic Auth API key

We are deprecating the use of API keys for authentication. This means that all integration should be using OAuth for authentication of users instead of individuals API keys.

In preparation for the deprecation, We are providing a migration mechanism from API keys to OAuth2 access and refresh tokens for applications that have previously relied on API keys. It implements the standard OAuth 2.0 Resource Owner Password Credentials grant flow.

What You’ll Need:

  • User's account URL
  • User’s API key
  • Client ID
  • Client Secret

You can obtain the client_id and client_secret by registering your application on our developer portal

How it works

You must make a POST request to the user's Capsule account url https://subdomain.capsulecrm.com/oauth/token and pass the API key parameters in the request body (as JSON or x-www-form-urlencoded):

  "client_id": "1bki1bki1bki8",
  "client_secret": "4tlbky534tlbky534tlbky534tlbky534tlbky534tlbky533l",
  "grant_type": "password",
  "username": "1600ecf01600ecf01600ecf01600ecf0",
  "password": "x"


Name Type Description
grant_type String This should be set to password
username String User’s API key.
client_id String The client ID you received when you registered the application.
client_secret String The client secret you received when you registered the application. Not required for "installed applications"

Note: The password parameter is optional and will be ignored even though it is required for this type of OAuth flow. You are free to provide any value in the password parameter, or not include it at all.


If successful, the app will be authorized on behalf of the user, and the response will contain a JSON object with the access and refresh token, the granted scope, the token type (which is always bearer), the expiration time of the access token, and the subdomain of the user’s capsule account.

HTTP/1.1 200 OK

    "scope":"read write",
    "subdomain": "demo"

Future requests should be authenticated using this access token and the user's API key should be discarded.

After the access token expires, you can use the refresh token to obtain a new access token. See the Refresh access token section of our authentication documentation for details.

Error responses

Subdomain not found

HTTP/1.1 404

  "message": "subdomain not found"

There is no Capsule account associated with this subdomain. This is most likely because the Capsule account was canceled.

Incorrect API Key

HTTP/1.1 400

  "error": "invalid_grant",
  "error_description": "Incorrect API Key"

The API key is invalid. This can happen if the user was deleted, or the API was reset.

In either of this cases the API key (and subdomain) cannot be used anymore to access the API or upgrade to OAuth 2. You should discard the key and ask the user to authorize your application using the OAuth2 flow.

Authorization for new users should go through OAuth2 flow. See our documentation for more details.