Skip to content
Last updated

日本語版

Introduction

This reference site provides documentation for LegalOn's RESTful API.

Obtaining an Access Token and Making 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.

Obtaining Credentials

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

  • Display name for management
    • Enter a name for identifying 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 registration, the generated API credentials will be displayed.
Please note that API credentials are shown only at the time of issuance.

Additional Notes on API Calls

  • The value of ${server URL} depends on your LegalOn contract 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}

Receiving a Response

API calls will return responses depending on the result.

Normal Cases

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.

Error Cases

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.

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, only the permissions selected at the time of API credential issuance may be reflected.
  • 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