Skip to content
Last9
Book demo

Getting started with API

Step-by-step walkthrough on how to obtain the API tokens for performing various operations with Last9

The API provides a programmatic method to access and operate Last9. This exposes a subset of features and actions that can be performed on Last9 as REST APIs. For example, you can send change events to Last9 using these APIs or you can generate alert rules.

Access Requirements

Access to the API Access page and token generation is controlled by user roles:

  • Admins can generate and revoke refresh tokens, and exchange them for access tokens
  • Editors can exchange existing refresh tokens for access tokens, but cannot generate new refresh tokens
  • Viewers cannot access the API Access page

If you need API access as an Editor, ask your organization’s Admin to generate a refresh token for you.

Base URL

The base API URL can be obtained from the API Access page. It is in the following format:

https://{domain}/api/{version}/organizations/{org}/{endpoint}

The {org} parameter is your unique organization slug.

Tokens

Authentication is performed using Bearer access tokens. The API Access page has two tabs:

Refresh Tokens (Admin Only)

Admins can create named refresh tokens with specific scopes (read, write, or delete). Each refresh token:

  • Has a descriptive name for identification
  • Is associated with a specific scope
  • Can be revoked at any time by an Admin
  • Is used to generate short-lived access tokens

To create a refresh token:

  1. Navigate to the Refresh Token tab
  2. Click New token
  3. Enter a descriptive name and select a scope
  4. Click Create and securely store the generated token

Refresh tokens are shown only once when created. Store them securely as they cannot be retrieved later.

API Access — Refresh Token tab

Access Tokens

Access tokens are short-lived tokens generated from refresh tokens. Both Admins and Editors can exchange a valid refresh token for an access token:

  1. Navigate to the Access Token tab
  2. Paste your refresh token
  3. Click Generate to receive an access token

API Access — Access Token tab

Token Revocation

Admins can revoke refresh tokens at any time from the Refresh Token tab. When a refresh token is revoked:

  • The refresh token immediately becomes invalid
  • Any access tokens generated from that refresh token will be rejected
  • This provides a security mechanism to invalidate compromised credentials

Token Expiry

Access tokens expire in 24 hours. Your application should handle token expiration by using the refresh token to generate a new access token.

The following error is returned when an access token expires:

{ "error": "Authorization token is expired" }

To generate a new access token, use the refresh token endpoint:

POST https://app.last9.io/api/v4/oauth/access_token

The OAuth endpoint does not include the organization in the URL. Use the exact URL shown above, not the organization-specific base URL.

Request Body:

{
  "refresh_token": "eyJhbGciOiXXXXXXXXXXXXX.eyJleHXXXXXXXXX.XXXXXXXXXOwuvUNA"
}

The response of this endpoint will contain a pair of access tokens and refresh tokens if the refresh token in the request body is valid.

Response

{
  "access_token": "eyJhbGciOiXXXXXXXXXXXXXX.eyJleHXXXXXXXXX.XXXXXXXXXOwuvUNA",
  "expires_at": 1587412870,
  "issued_at": 1587240070,
  "refresh_token": "eyJhbGciOiXXXXXXXXXXXXX.eyJleHXXXXXXXXX.XXXXXXXXXOwuvUNA",
  "type": "Bearer",
  "scopes": ["read", "write", "delete"]
}

Usage

The tokens are specifically separated based on the scopes they are authorized to perform based on the impact they might have on the system’s overall behavior.

  • Read Tokens: Have a minimum impact on the performance of the Last9 application. These are to be specifically used for reading the current state of the data
  • Write Tokens: Use this token to create or modify data in any supported entity. This could change the behavior of your usage of Last9
  • Delete Tokens: Use this token judiciously. This could break the processes and cause an irrevocable state through missing data

Authentication & Authorization

All public API endpoints require a Token to be supplied as an authorization header for all requests. The token is used to identify the user/application and authenticate the requests to API. The header name must be X-LAST9-API-TOKEN.

Making your first API request

Please follow the steps below to create our first API request for a change event.

Step 1: Generate Tokens

  1. Navigate to the API Access page
  2. If you’re an Admin, create a new refresh token with write scope from the Refresh Token tab
  3. Exchange the refresh token for an access token from the Access Token tab
  4. Copy the generated access token for use in your API request

Step 2: Base URL

The base URL of your instance can be obtained as specified in the Base URL section above.

Step 3: Making the API request

The endpoint for creating change events is

PUT /change_events
{
  "timestamp": "2024-01-15T17:57:22+05:30",
  "event_name": "new_deployment",
  "event_state": "start",
  "attributes": {
    "env": "production",
    "k8s_cluster": "prod-us-east-1",
    "app": "backend-api"
  }
}

The cURL request looks as follows:

curl --location --request PUT 'https://app.last9.io/api/v4/organizations/github-prathamesh-sonpatki/change_events' \
--header 'X-LAST9-API-TOKEN: Bearer <WRITE_ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
  "timestamp": "2024-01-15T17:57:22+05:30",
  "event_name": "new_deployment",
  "event_state": "start",
  "attributes": {
    "env": "production",
    "k8s_cluster": "prod-us-east-1",
    "app": "backend-api"
  }
}'

Step 4: Verify the response

The API will return the following response in case of success with HTTP status code 200.

{
  "message": "success"
}

Troubleshooting

Please get in touch with us on Discord or Email if you have any questions.