Skip to main content

REST API authentication and authorization

Before you can run automation scripts that contain Lenovo XClarity One REST APIs, you must set up an REST API key that is used for authentication and authorization.

Attention
The REST APIs are currently under development. Take care when creating custom scripts as some REST APIs might change in future releases, and those changes might require you to update your scripts.

To set up one or more REST API keys, click REST API keys on the context menu from the Settings view, and then client the Add icon (Add icon).

You can choose what privileges you want to give to the REST API key.

  • Monitor Resources. Allows scripts to monitor todos, events, alerts, and jobs for resources that you can access.
  • View Organization Users. Allows scripts to retrieve organization user information.
  • Manage organization users. Allows scripts to retrieve information about organization users, invite new users, assign roles, and enable or disable users.
  • View Hubs. Allows scripts to retrieve hub information.
  • Manage Hubs. Allows scripts to retrieve information about, add (connect), remove (disconnect), and enable or disable hubs.
  • View Devices. Allows scripts to retrieve information about devices.
  • Manage Devices. Allows scripts to retrieve information about, discover, manage, and unmanage devices.
  • Manage Device Power. Allows scripts to power on and off devices.

When you set up a new API key, the portal generates a unique client ID and client secret for that key. This secret expires after 6 months. When the key expires, the API key is disabled. The only way to re-enable (activate) the key is by regenerating the secret. From the REST API keys page, click the Regenerate secret icon (Refresh icon). Each time that you regenerate the secret, you then need to update the secret in your custom scripts.

Attention

  • Immediately after creating a new API client, ensure that you copy and record the client ID and client secret in a safe location. The secret is shown as plain text only when the API key is first created. In the detailed view, only the last three characters of the secret is viewable for security purposes. If you lose the client secret, you can regenerate a new secret for the API client by clicking the Regenerate secret icon (Refresh icon).

  • If you disable an API key, client connections using that API key remain open until token expires.

  • If you disable an organization or perform an emergency shutdown, all API keys are automatically disabled, and open connections are immediately invalidated. Clients cannot authenticate, perform operations, or access resources. After the organization is reactivated, you can regenerate the secret to re-enable each API key.

Authentication​

To authenticate your automated scripts, you need to generate a JWT access token by making a POST request to the access token request URL, which you can find on the API key details page.
API key detail page

The access token expires after 5 minutes, regardless of activity.

Request body – application/x-www-form-urlencoded

  • grant_type – string (required) Grant type. This is always client_credentials.
  • client_id – string (required) Unique client ID that was generated for the REST API key
  • client_secret – string (required) Unique client secret that was generated for the REST API key
For example:
grant_type=client_credentials
client_id=2655ACB78E65400D9F67BEEBC2030086_8270E1264DCB45BF91D4DDE443D53F90
client_secret=pGT0jQbBx9tfbm0hrQDj3oZVi9cg6l3L

Response body – application/json

  • 200 (Success)

    • access_token – string. JWT access token
    • expires_in – string. Token expiration time, in seconds
    • token_type – sring. Token type. This is always Bearer.
    For example:
    {
        "access_token": "",
        "expires_in": "",
        "token_type": "Bearer"
    }

  • 400 (Failure - Invalid data) and 401 (Failure - Unauthorized)

    • status – string. Request status
    • code – string. Message code
    • text – string. Message text (translated)
    • description – string. Additional information to clarify the reason for the message (translated)
    • userAction – string. User actions that can be taken to recover from the error (translated)
    • recoveryURL – string. Link to more information or recovery actions, if available