Skip to content
Last updated

日本語版

Getting started

This reference site documents LegalOn's RESTful API.

Get an access token and make API calls

LegalOn's API follows the OAuth 2.0 Client Credentials Flow.
You must request an access token by specifying grant_type=client_credentials.

Flow of obtaining an access token and using the API

  1. The client sends a request to obtain an access token using API credentials.
  2. If the request succeeds, the authorization server returns an access token.
  3. The access token is then used to make API calls to the resource server (LegalOn API).
  4. If the API call succeeds, the resource server returns a JSON-formatted response.

Get API credentials

API credentials can be obtained from LegalOn's admin console.
Please go to [User settings] > [API Integration] to retrieve them.
When issuing API credentials, fill in the following fields:

  • Display name
    • Enter a display name to help you manage these API credentials.
  • Expiration period
    • Select the validity period for the API credentials from:
      • 7 days
      • 30 days
      • 60 days
      • A custom number of days
      • No expiration

After you create the credentials, they will be displayed.
API credentials are shown only once, when they are issued.

Additional notes on API calls

  • The value of ${server URL} depends on your LegalOn region.
    You can check the region on the license screen in the LegalOn [Admin settings].
    If the [Admin settings] menu is not visible, contact your tenant administrator.
    • US region: https://public-api.legalontech.com
    • JP region: https://public-api.legalon-cloud.com
  • Always include Authorization and Content-Type headers in your requests.

Sample code

Below is a sample code snippet for obtaining an access token using API credentials.

curl

    curl -H "Authorization: Basic ${API credentials}" \
         -H "Content-Type: application/x-www-form-urlencoded" \
         -d "grant_type=client_credentials" \
         -X POST ${server URL}/oauth/token

Example response

If the access token request succeeds, you will receive a response like the following.
Use ${API base URL} and ${access token} to make API calls. The access token is valid for 1200 seconds (20 minutes) after issuance. (Note that this validity period may change.)

    {
      "access_token": "${access token}",
      "expires_in": 1200,
      "token_type": "Bearer",
      "api_base_url": "${API base URL}"
    }

How to call the API

Client applications can call public APIs by specifying the API access token and the required request parameters.

Request example:

    curl -X POST \
         -H "Authorization: Bearer ${access token}" \
         -H "Content-Type: application/json" \
         -d "${request parameters}" \
         ${API base URL}/${path}

Receive a response

API calls will return responses depending on the result.

Success

The response will include the status code and response body defined by the target API.
The response body may be extended, so implement your client to skip unknown JSON fields.

Errors

A status code and error message appropriate to the cause will be returned.

Examples:

  • Invalid access token
  • Missing parameters
  • Insufficient permissions, etc.

Common response headers

The following headers are returned for each request:

  • X-RateLimit-Limit
    • Maximum allowed number of requests
  • X-RateLimit-Remaining
    • Number of remaining requests
  • X-RateLimit-Reset
    • Seconds until the rate limit resets
  • X-Request-Id
    • Unique ID assigned to each request

Rate limit

There is a limit on the number of API calls.
If the limit is exceeded, HTTP status code 429 (Too Many Requests) is returned. (If you need to adjust your rate limits due to specific circumstances, please contact us to discuss your situation.)

Requests counted toward the rate limit

All requests count toward the rate limit except in the following cases.

Excluded cases:

  • When the public API service is entirely unavailable
  • When the API access token is invalid
  • When the API access token has expired
  • When a rate limit error (429) has already been returned

Note:

Even if a request fails, it counts as a valid call if the failure is caused by unmet request conditions (permissions, parameters, resource state, etc.).

FAQ (Frequently Asked Questions)

  • Q1. What should I do when the access token expires?
    • A. Request a new access token by using your API credentials again. Refresh tokens are not provided.
  • Q2. How are the "permissions" included in the access token determined?
    • A. They are based on the permissions assigned to the user linked to the API credentials.
      In the future, we plan to support limiting the access token to the permissions selected when the API credentials are issued.
  • Q3. What happens if I send many requests in a short period of time?
    • A. Your requests may be rejected if you exceed the rate limit.
 
Next page