Skip to main content

Understand Tenant Management API

Contributors

You can perform system management tasks using the Tenant Management REST API instead of the Tenant Manager user interface. For example, you might want to use the API to automate operations or to create multiple entities, such as users, more quickly.

The Tenant Management API:

  • Uses the Swagger open source API platform. Swagger provides an intuitive user interface that allows developers and non-developers to interact with the API. The Swagger user interface provides complete details and documentation for each API operation.

  • Uses versioning to support non-disruptive upgrades.

To access the Swagger documentation for the Tenant Management API:

  1. Sign in to the Tenant Manager.

  2. From the top of the Tenant Manager, select the help icon and select API documentation.

API operations

The Tenant Management API organizes the available API operations into the following sections:

  • account: Operations on the current tenant account, including getting storage usage information.

  • auth: Operations to perform user session authentication.

    The Tenant Management API supports the Bearer Token Authentication Scheme. For a tenant login, you provide a username, password, and accountId in the JSON body of the authentication request (that is, POST /api/v3/authorize). If the user is successfully authenticated, a security token is returned. This token must be provided in the header of subsequent API requests ("Authorization: Bearer token").

    For information about improving authentication security, see Protect against Cross-Site Request Forgery.

    Note If single sign-on (SSO) is enabled for the StorageGRID system, you must perform different steps to authenticate. See the instructions for using the Grid Management API.
  • config: Operations related to the product release and versions of the Tenant Management API. You can list the product release version and the major versions of the API supported by that release.

  • containers: Operations on S3 buckets or Swift containers.

  • deactivated-features: Operations to view features that might have been deactivated.

  • endpoints: Operations to manage an endpoint. Endpoints allow an S3 bucket to use an external service for StorageGRID CloudMirror replication, notifications, or search integration.

  • grid-federation-connections: Operations on grid federation connections and cross-grid replication.

  • groups: Operations to manage local tenant groups and to retrieve federated tenant groups from an external identity source.

  • identity-source: Operations to configure an external identity source and to manually synchronize federated group and user information.

  • regions: Operations to determine which regions have been configured for the StorageGRID system.

  • s3: Operations to manage S3 access keys for tenant users.

  • s3-object-lock: Operations on global S3 Object Lock settings, used to support regulatory compliance.

  • users: Operations to view and manage tenant users.

Operation details

When you expand each API operation, you can see its HTTP action, endpoint URL, a list of any required or optional parameters, an example of the request body (when required), and the possible responses.

example showing GET groups operation in Swagger API

Issue API requests

Caution Any API operations you perform using the API Docs webpage are live operations. Be careful not to create, update, or delete configuration data or other data by mistake.
Steps
  1. Select the HTTP action to see the request details.

  2. Determine if the request requires additional parameters, such as a group or user ID. Then, obtain these values. You might need to issue a different API request first to get the information you need.

  3. Determine if you need to modify the example request body. If so, you can select Model to learn the requirements for each field.

  4. Select Try it out.

  5. Provide any required parameters, or modify the request body as required.

  6. Select Execute.

  7. Review the response code to determine if the request was successful.