Access Domo's APIs using OAuth 2.0 security

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.

Within the developer portal you will need login with the name of your Domo instance.  Once you have logged in, you will then need to navigate to your user avatar and select “Create New Client” in the dropdown list.

You can create clients as needed; for example, you may want to create one application just to manage your data. You may want another to manage your users. Before your application can generate access tokens and access the API, you need to generate a client id and secret.

When creating your Client ID and Client Secret, you’ll be asked to specify the “scope” of the program. The scope is a security measure that allows you to limit the functionality an application has access to.  Selecting only the “data” scope, for example, limits calls to data-related APIs, while a client generated with “data” and “user” scopes would have access to both data and user-related APIs.

You can also view, delete or otherwise manage existing clients as well.

To request an access token, make the following request with your generated client ID and secret.

$ 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-b2co-4a99-8561-174p4b153fsa:f103fc4bkd08bdh0p8edc9a1913e3f5266447a06d1d2751258c89771fbcc8087 "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": "GhX52tNtsnyQQybNBtjrc9KbH4DhKTxPbdHcvfHnX3NYGjBWSzdP9kNxWbwDdNMSYqt3VKSBxVXAMYjBAhtvMpscB9edmSjd8BE3gfpGw8uAZhwAHccekG2yBZMse7CPHQkv8JSKcykz4gbcuWak8RpPkVCc8cCZzAzmE7bXQrAGwmPG6wh7YMmBEB6ZPtz8ZYgBNH7S5MYwsJ295A99Bqz7Jn83U333cfT5JT5s5RSF9sUebAKw5cedBU4kf6qq9pFxJ3pcPKqbtZdzRVz4WtRDXsd87FjSVCFk36TRS6Q9GDdM2WZXJjKpEUtCDpX2GSBwsBJgWdWGe3VnTp9U46Fw5dsbBQwDZ4VSQuk9UKJdqfkR5WrfYueVReUKSjCHS6CXjs5RRBSSAmejE7wtDWfdJ2FGnZ9sBDK4eUgWCz8NXSXtWhQtQdenSM47rbSsWF9r8QwChDdQ93NBWYFfsxKcgBa9J6UyaG3T2GWMvgTHc8vTPMhhsS6ceMfEUJUKpQkuHsgtcC7uWWrYnnJFenR34Dr2GNAxkU3CPjys4M3xQNJRkbXyRwtEsEs275MnKQbyF4bayZKU7uJFQhVSjujmf2KRQrsnKamhNSfhJhyttaG48ZuYnTCnCVUvdJF7ATUh",
    "customer": "acmecompany",
    "expires_in": 3599,
    "jti": "81dece4c-df73-4569-853c-2d1a328897fd",
    "role": "Admin",
    "scope": "data user",
    "token_type": "bearer",
    "userId": 964382593
}

The JSON response body might include more fields than those listed in the example response, but the important fields to be aware of are: access_token, and expires_in.

Every subsequent request must have an access token added as a header. Access tokens expire in approximately an hour; after that you'll need to get a new access token.

After you’ve obtained an access token, you’ll need to send it with every request to the Domo API in an HTTP authorization header.
Let’s say you wanted to call Domo’s API to get a list of your DataSets within Domo. You would make the following GET request (replacing "{access-token}" with the access token obtained in the previous step):

$ curl -v -H Authorization:'bearer {access-token}' "https://api.domo.com/v1/datasets"

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.