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 special permission​

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

To assign the developer special permission:

  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 special permission to existing users

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

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

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

Revoke developer special permission​

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

caution

Revoking the developer special permission revokes credentials created by the user and prevents the user from generating new credentials.

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

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

The developer special permission 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 special permission 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 special permission 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.

The name helps you find your credentials quickly in the list

  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.

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

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 special permission.

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.

Sandbox Environment

When utilizing our API endpoints as outlined in the Developer Hub, it's essential to modify the URL structure for sandbox testing. All API endpoint URLs provided in the documentation are initially configured for the production environment using the base URL https://api.onna.com. However, you should replace this with https://sandbox.onna.com/api for the sandbox environment.

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.

Your first request​

Verify that your token is working by requesting your user ID via the API.

curl --location --request GET 'https://api.onna.com/v1/oauth/user' \
--header 'Authorization: Bearer d3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0deMOd'
{
    "id": "jane.doe@acmecorp.com",
    "account_id": "acmecorp",
    "name": "jane.doe@acmecorp.com",
    "surname": "Doe"
}

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 special permission, and how users with those special permission can create credentials and tokens to authenticate their requests.

Last updated on