API Functionality & Management
While all operations can be performed through the web based console, users can also perform operations programmatically using Open API compliant REST APIs. The Controller is designed and developed with an API First philosophy. Both the RCTL CLI Utility and the Web Console both use the REST APIs underneath the covers for all their functionality.
API Keys and RCTL CLI Config Settings¶
API Keys and RCTL CLI Config Settings are aimed to enhance the configuration and management of API keys and RCTL Config within the organization. The Org Admin has the ability to establish a default duration for expiration. Additionally, Org Admin can create users and define the expiration timeframe. Expiry durations can be specified in hours, with a minimum of 1 hour.
Note: In the event of receiving an exception request, the org admin has the option to either generate a key on behalf of the user or modify the expiration period specifically for that user.
Users also have the option to set an expiry duration when creating an API key or downloading an RCTL Config. However, this expiry duration cannot exceed the duration set in the org-wide setting or the expiry duration specifically configured for the user. If the user does not specify an expiry duration, it will default to the organization-wide setting or the user-specific configuration (whichever is a higher number).
Also, Org Admins will have the capability to create API keys for themselves or on behalf of other users. They will be able to configure an expiry interval that can override other configurations, allowing for durations that exceed the limits set for the organization or individual users. To provide visibility into the expiry status of API keys, details regarding the expiry interval is available as shown in the below image. This will help users and administrators track the expiration dates of API keys more effectively.
- Please make sure to copy the API key (on a new API key creation) as you won't be able to view this again
- Email notifications will be sent to users regarding imminent expirations, 7 days and 1 day prior to the expiry, as appropriate.
- If an expired API key or RCTL Config is used, the error message will explicitly indicate that the authentication failed due to the key's expiration
- API keys that have been expired for over 90 days will be automatically deleted
In order to manage their API Keys, users have to click on "My Tools" and Select "Manage Keys"
- API keys are uniquely generated for every user
- Users can have one or many API keys associated with their Identity
- Users can generate new APIs keys at any time.
- Users can also delete API keys anytime.
All API calls are performed over a https protected, secure channel. Every API call is authenticated and access is authorized based on the user's role. An immutable audit trail is maintained centrally for all actions performed via APIs.
sequenceDiagram participant API Caller participant Rafay Platform Note right of API Caller: https rect rgb(191, 223, 255) API Caller->>Rafay Platform: API Request (API Key) Note right of Rafay Platform: AuthN, AuthZ & Audit Rafay Platform-->>API Caller: Response end
Access the Swagger UI¶
Use the following links to access the Swagger UI for the REST APIs.
It is recommended to use v3 APIs wherever available. v3 APIs were designed to enable a more consistent experience and follows a declarative usage pattern.
Authorized users with access to an Org or Partner Operations Console can also access the Swagger UI for the REST APIs directly from the Console
- Login to the Console
- Click API DOCS from the controller menu bar
Opt for the necessary version, whether V3 or V2, with a preference for V3 as the recommended choice.
You will be presented with a familiar Swagger UI for the REST APIs. Ensure you generate and use API keys before you try the APIs against your Org.
The REST API is designed to be versioned. The current version is ‘v1’ and is accessible through the following URL:
These REST APIs are meant for SaaS multi-tenant, optionally white labeled KaaS partners/customers. These APIs are primarily meant for End Customer Organization (aka Org) lifecycle management actions.
- Create an Org
- Sign Up a New Org
- Get list of all Orgs
- Get a specific Org's details
- Delete Org
- Activate an Org
- Deactivate an Org
- Approve an Org
- Add user to an Org
- Generate an API key for a User in an Org
These REST APIs (Get, Post, Put and Delete) can be used for performing all CRUD actions on objects in a specific Organization (Org).
- Cluster Override
- Infra Provisioner
- Cluster Templates
- Convert to Managed
- Backup and Restore
Authentication is the process of proving your identity to the Controller. Like the Username/Password pair used to access the Web Console, the Controller requires REST API callers authenticate using an "Access Key ID" and "Secret" for programmatic (API) access.
Security Best Practices¶
- For machine users, it is strongly recommended to use users that are only allowed programmatic access
- Once created, ensure you save the secret because it is not displayed after that.
- Securely store your secret access keys. Remember that anyone who gets access to your "access key" has the same level of access to your resources that you do.
- Access keys are not auto-generated for new user accounts. They are generated on demand by the user and are managed via the Console.
- If you have lost your secret access key, revoke it and generate a new access key.