Skip to main content

Authentication

To interact with the API, you must authenticate your requests with an access token.


Our API uses OAuth 2's Client Credentials Grant to authenticate your requests. This grant type is especially suited for machine-to-machine (M2M) applications, such as the applications you build on top of the Onna platform.

Diagram of the authentication flow

Assign developer role

Assigning the developer role is the first step to allow your organization to start using our API. If you're an Onna admin, you can assign the developer role to existing users. This role allows developers to generate their own set of credentials from the Platform API app in the UI.

To assign the developer role:

  1. After logging in as an admin user, select the Platform API app in your home page.
https://enterprise.onna/ACMECORP

Users with the admin role see the Platform API app in their home page

  1. In the MANAGE section of the nav bar, select Developers, then select +.
https://enterprise.onna.com/ACMECORP/developer-api

The Developers section is where admins can assign a developer role to existing users

  1. In the Add developers dialog, enter the developers you want to grant the role to, then select Add.
https://enterprise.onna.com/ACMECORP/developer-api

When you assign the role developer, users with this role start seeing the Platform API app in their home page

The user now has a developer role, can generate their own credentials, and start building with the API.

Revoke developer role

You can revoke the developer role from users at any time from the Platform API app.

caution

Ask your developer to delete any active credentials before revoking their role. While users that have the developer role revoked cannot generate new credentials, old credentials will still work if they haven't deleted them.

  1. In the Developers section, select the ellipses () next to the user you want to revoke the role from, then select Remove developer.

Revoking the developer role from a user will prevent them from generating new credentials

The developer role is revoked from the user. They will stop seeing the Platform API app and won't be able to generate new credentials.

Create credentials

When you are granted the developer role by your admin you can manage your own credentials.

You can have a separate set of credentials for each application you're working on.

  1. After logging in, select the Platform API app in your home page.
https://enterprise.onna/ACMECORP

Users with the developer role see the Platform API app in their home page

  1. In the DEVELOP section of the nav bar, select API credentials, then select +.
https://enterprise.onna.com/ACMECORP/developer-api

Use the API credentials section to manage your credentials

  1. In the Create API credentials dialog, enter a name for your credentials, then select Create.

Store the credentials somewhere safe. You won't be able to see the client secret after you close this dialog

  1. Use the Keep the client secret safe! dialog to copy your credentials and store them somewhere safe, then select Done.
caution

When you close the dialog, the client secret is encrypted and won't be visible anymore. If you lose it, you must generate new credentials.

The name helps you find your credentials quickly in the list

You can now use the credentials to authenticate and exchange them for a bearer token. You can then use that token to authorize requests to the API.

Request tokens

To access the API, you must authenticate your requests by including a valid access token in a request’s header. The token is used by the platform to verify that you’re authorized to make requests.

You can obtain a token by exchanging it with your client credentials. You can create the credentials from the Platform API app in the UI once the admin assigned you the developer role.

Tokens have a fixed lifetime of 1 hour

For security reasons, tokens expire after 1 hour (3599 seconds) and cannot be refreshed. If you make a request with an expired token, you’ll receive a 401 error. When that happens, generate a new token and use it in your following requests.

To request a token:

  1. Send a POST request that includes your client ID and client secret to the /oauth/token endpoint.
curl --request POST \
--url 'https://api.onna.com/v1/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=YOUR_CLIENT_ID' \
--data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \
--data-urlencode 'grant_type=client_credentials'

Where:

  • YOUR_CLIENT_ID is the unique client ID that you generated in the Platform API app. For example, 123123123
  • YOUR_CLIENT_SECRET is the unique client secret that you generated in the Platform API app. For example, 123123123

A successful response returns a valid token.

{
"access_token": "d3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0deMOd",
"token_type": "bearer",
"expires_in": 3599
}

Now you’re ready to use the token to make requests.

Use tokens in your requests

When you make requests, include your token as an authorization bearer in your requests' headers.

The example below shows a request to create a new workspace.

curl --location --request POST 'https://api.onna.com/v1/workspaces' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer d3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0deMOd' \
--data-raw '{
"name": "Foo",
"description": "Bar"
}'

Recap

In this article you learned how authentication works in Onna, how to manage developer roles, and how users with those roles can create credentials and tokens to authenticate their requests.