Skip to content
Last updated

日本語版

Introduction

LegalOn API is a RESTful API. Getting started takes the following three steps.

  1. Create API credentials (in the admin console)
  2. Obtain an access token (OAuth 2.0 Client Credentials)
  3. Call the API (send requests to api_base_url/rest/v1)

Important:

  • The token endpoint depends on your contracted region.
  • The base URL for API calls is built using api_base_url returned by the token response (append …/rest/v1 as defined in the OpenAPI “Servers”).

Obtaining API Credentials

How to obtain

API credentials can be created from the LegalOn admin console.

Fields to enter when creating credentials

FieldDescriptionExample / Options
Display nameA name used to manage your API credentials. Choose a name that clearly indicates the purpose.prod-batch-integration / stg-test-client
ExpirationExpiration of the API credentials. Select according to your operational policy.7 days / 30 days / 60 days / Specify by day / No expiration

Operational tip
Using a display name that includes “purpose + environment” makes it easier to audit credentials and assess impact when they expire.

After creation (Important)

Once created, the API credentials will be shown on the screen.
API credentials are displayed only at the time of creation and cannot be shown again.
Store them securely.

Obtaining an Access Token

How to obtain

Access tokens are obtained using the OAuth 2.0 Client Credentials Flow.

Sample (curl)

curl -H "Authorization: Basic ${API_CREDENTIALS}" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials" \
     -X POST ${api_base_url}/oauth/token
  • ${api_base_url} depends on your region.
  • ${API_CREDENTIALS} is the value issued in the admin console.

Retrieving the response

If the token request succeeds, the following response is returned.

What to do next

  • For subsequent API calls, send access_token as Authorization: Bearer <token>.
  • Use api_base_url from the token response as the API base URL (your API calls are based on {api_base_url}/rest/v1).

About expiration
The access token expires 1200 seconds (20 minutes) after issuance.
This value may change in the future. In your implementation, rely on expires_in.

Response body (example)

{
  "access_token": "<ACCESS_TOKEN>",
  "expires_in": 1200,
  "token_type": "Bearer",
  "api_base_url": "https://${api_base_url}"
}

Field reference

FieldTypeDescription
access_tokenstringAccess token used to call the API
expires_innumberToken lifetime in seconds
token_typestringToken type (typically Bearer)
api_base_urlstringBase URL for API calls

Notes for API calls

  • Access tokens are short-lived. If you receive 401 Unauthorized, obtain a new token first.
  • permissions are determined based on the privileges of the user linked to the API credentials (see FAQ for details).
  • Responses may include X-Request-Id. We recommend logging it for support inquiries and troubleshooting.

Calling the API

How to call

The API base URL is {api_base_url}/rest/v1 (api_base_url is taken from the token response).

Sample

curl -X GET \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  ${api_base_url}/rest/v1/users?page_size=50

Retrieving the response

Depending on the result of the API call, the following responses are returned.

Success (2xx)

  • The status code and response body defined by the target API are returned.

Implementation note (Forward compatibility)
The response body may be extended with additional fields in the future.
Implement your client so that it ignores unknown JSON fields (do not fail on extra fields).

Error (4xx / 5xx)

  • An appropriate status code and error information are returned depending on the cause.

Examples (common causes)

  • Invalid access token (e.g., 401 Unauthorized)
  • Invalid parameters (e.g., 400 Bad Request)
  • Insufficient permissions (e.g., 403 Forbidden)
  • Rate limit exceeded (e.g., 429 Too Many Requests)

Common response headers

The following headers may be included in API responses.

HeaderDescription
X-RateLimit-LimitConfigured request limit
X-RateLimit-RemainingRemaining number of requests
X-RateLimit-ResetSeconds until the limit resets
X-Request-IdUnique identifier for each request (useful for support inquiries)

Operational tip
If you receive 429 Too Many Requests, wait and retry based on X-RateLimit-Reset.
When contacting support, include X-Request-Id.

Rate Limits

API calls are subject to rate limits. If you exceed the limit, the server returns 429 Too Many Requests.

Requests counted toward the limit

In principle, all requests count toward the rate limit.

Excluded cases:

The following cases are not counted toward the rate limit.

  • The Public API service is down (service-wide outage)
  • The API access token is invalid
  • The API access token has expired
  • A rate-limit error (429) has already been returned

Note:

Important
Even if a request fails, errors caused by unmet request conditions—such as permissions, parameters, or resource state—are counted as valid requests.

FAQ

What should I do if my access token expires?
If the access token expires, send the token request again using your API credentials and obtain a new access token.

  • Refresh tokens are not provided.
  • If you receive 401 Unauthorized, try obtaining a new token first.

How are permissions in the access token determined?
permissions are determined based on the privileges of the user linked to the API credentials.

  • In the future, we plan to allow reflecting only the permissions selected when issuing the API credentials.

What happens if I send many requests in a short time?
If you send many requests in a short period, requests may be rejected due to rate limits (e.g., 429 Too Many Requests).

  • Refer to X-RateLimit-* headers and wait/retry accordingly.
 
Next page