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.

Manage Keys

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.

Manage Keys

Important

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

API Keys¶

In order to manage their API Keys, users have to click on "My Tools" and Select "Manage Keys"

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.

API Authentication¶

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.

Production Orgs:

Preview Orgs:

Note

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.

Link to REST APIs

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.

Swagger UI for REST APIs

Versioning¶

The REST API is designed to be versioned. The current version is ‘v1’ and is accessible through the following URL:

https://<host>/<module>/v1/

Partner APIs¶

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

Administration API¶

These REST APIs (Get, Post, Put and Delete) can be used for performing all CRUD actions on objects in a specific Organization (Org).

Projects
Clusters
Blueprints
Addons
Namespaces
Workloads
Catalogs
Repositories
Agents
Users
Groups
Triggers
Pipelines
Cluster Override
Infra Provisioner
Cluster Templates
Gateway
Convert to Managed
Roles
Backup and Restore

Authentication¶

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.