Skip to main content
API Base URL
Domo API Server: https://api.domo.com
Security: Bearer AuthBasic authentication is a simple authentication scheme built into the HTTP protocol. To use it, send your HTTP requests with an Authorization header that contains the word Basic followed by a space and a base64-encoded string username:password.Example: Authorization: Basic ZGVtbzpwQDU1dzByZA==

​
OAuth Authentication

The following section provides more detail on the OAuth authentication and authorization approach. In order to access Domo APIs, a user must first be authenticated (prove that they are whom they say they are) through a client ID and client secret. Once a user has been authenticated, they can then create an access token to authorize what the scope of functionality will be available for each API for that specific access token.

​
Best Practice

The Domo SDKs (Java or Python) are often the recommended approach to leveraging the above Domo APIs: that’s because they provide a nice wrapper for each endpoint and automatically handle refreshing your access token. Learn more about our SDKs sdks.md.

​
Security Consideration

A Client ID is a public identifier while the Client secret is considered confidential.
Ensure these credentials are not placed in client or server-side code and are not committed to repositories. If accidentally posted to a public repo, rotate them ASAP. Do not store or transmit the secrets in insecure locations, server configuration files, log files, emails, messaging apps, etc. The clidntid and secret will be used in authorization requests to obtain access tokens. Always use secure protocols for such requests.

​
Quickstart

To leverage the APIs in Domo will require you to obtain an access token. This quickstart will walk you through the three steps needed to authenticate and begin developing.
  1. Create client ID and secret
  2. Create access token
  3. Use access token

​
Step 1: Create client ID and secret

In order to generate a client ID and client secret you will need your Domo instance name (i.e. the name preceding your domo.com URL, in the case of “acmecompany.domo.com” your instance name would be acmecompany). To create a client ID and secret you will need to log in within the Developer Portal. You will be prompted to enter your instance name and then your user credentials.
You’ll be redirected to the manage clients page where you can see your existing clients or create a new one). On the Developer Portal Homepage, if you’re logged in, you should also now see a “My Account” dropdown where you can manage clients, create a new one, or logout. After submitting successfully, you will now have a newly provisioned client ID and secret on the Manage Clients page.

​
Step 2: Create access token

Once you obtain your client ID and client secret you will then need to obtain your access token. You can do so in our interactive documentation using the Get Access Token endpoint or using the example curl requst below. 
curl -v -u {CLIENT\_ID}:{CLIENT\_SECRET} "https://api.domo.com/oauth/token?grant\_type=client\_credentials&scope={SCOPE}"
Please note that in the above example, when using the -u command line option, cURL correctly formats the client id and secret to a basic authorization header. If you are programmatically requesting access tokens, make sure that you are correctly including the basic authorization header with your Base64 encoded credentials. See the OAuth client credential grant type access token request specification and the HTTP Basic Authentication Scheme specification for more information. An example with your scope,client_ID, and client_secret would look similar to below: 
curl -v -u 441e307a-b2a1-4a99-8561-174e5b153fsa:f103fc453d08bdh049edc9a1913e3f5266447a06d1d2751258c89771fbcc8087 "https://api.domo.com/oauth/token?grant\_type=client\_credentials&scope=data%20user"
Once you request a token with the curl command, you should receive the following response with an associated access token: 
HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Cache-Control: no-store
Connection: keep-alive
Content-Type: application/json;charset=UTF-8
Date: Thu, 03 Aug 2017 17:05:58 GMT
Expires: 0
Pragma: no-cache
Pragma: no-cache
Server: nginx
Transfer-Encoding: chunked
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block

{
    "access_token": "<your-valid-oauth-access-token>",
    "customer": "acmecompany",
    "expires_in": 3599,
    "jti": "81dece4c-df73-4569-853c-2d1a328897fd",
    "role": "Admin",
    "scope": "data user",
    "token_type": "bearer",
    "userId": 964382593
}

​
Best Practice

Domo’s SDKs simplify the authentication process. Obtain a Client ID and Client Secret and then update the placeholders to begin developing.

​
Step 3: Use access token

Now that you have received your access token, you will use it for each of your request. It is recommended to simplify the process with the following request with: 
export ACCESS\_TOKEN\=<your-valid-oauth-access-token\>
Below is an example of a request with an example token: 
export ACCESS\_TOKEN\=<your-valid-oauth-access-token\>
Now that you’ve exported your token, you can dynamically populate when making calls to any of Domo’s API like in the example below: 
echo '{"name": "Sales Operations Team", "default": false}' | http -v POST https://api.domo.com/v1/groups Authorization:"bearer $ACCESS\_TOKEN" --pretty\=format

​
Important terms

OAuth 2.0: OAuth 2.0 is an authentication framework as defined by the RFC-6749 standard. OAuth 2.0 focuses on client developer simplicity while providing specific authentication flows for web and desktop applications. Generally speaking, OAuth provides clients with secure delegated access to server resources on behalf of a resource owner. It allows resource owners to authenticate and authorize third-party access to their server resources without the need to share personal credentials. Designed specifically to work with Hypertext Transfer Protocol (HTTP), OAuth uses short-lived access tokens, issued to a client by an authentication server, with the approval of the resource owner. The client then uses the access token to access the protected resources hosted by the resource server. Client ID: An ID used to uniquely identify a third-party client. Client Secret: A secret code that proves to the authentication server that the client program is authorized to make a request on behalf of the user. Client Secrets are required for OAuth 2.0. A program requesting an access token has to know the client secret in order to gain the token. This prevents malicious apps that have not been authorized from ever obtaining a valid access token. A Client Secret doesn’t state anything about authenticating a user; it’s simply authorizing an app to request access tokens. A client secret must be protected at all costs; if the secret is compromised, a new one must be generated and all authorized programs must be updated with the new client secret.

​
OAuth 2.0 handshake summary

authimage

​
Next Steps

Start experimenting with the Domo OAuth APIs. In addition to the above approach from the command line, you can also generate an access token and test using directly within the Domo Developer Portal.
getauthtokenpage.png

​
Need additional help?

No problem, we’d love to help. Explore our documentation or join other developers in Domo’s Developer Forum. For further help, feel free to email us or contact our sales team.