Skip to content

Infisical is the open-source platform for securing secrets, certificates, access, and AI Agents.

docs(api): add get started section (#8267)

Adrian Kahali2bb383f8a64e
diff --git a/backend/src/lib/api-docs/constants.ts b/backend/src/lib/api-docs/constants.ts
index cf91545042..ec9cad1cb5 100644
--- a/backend/src/lib/api-docs/constants.ts
+++ b/backend/src/lib/api-docs/constants.ts
@@ -106,7 +106,8 @@ export enum ApiDocsTags {
AgentVaultSessions = "Agent Vault Sessions",
AgentVaultProxies = "Agent Vault Proxies",
AgentVaultMembers = "Agent Vault Members",
- KmipServers = "KMIP Servers"
+ KmipServers = "KMIP Servers",
+ Instance = "Instance"
}
export const GROUPS = {
diff --git a/backend/src/server/routes/index.ts b/backend/src/server/routes/index.ts
index 38d0799349..d18edd49f3 100644
--- a/backend/src/server/routes/index.ts
+++ b/backend/src/server/routes/index.ts
@@ -212,6 +212,7 @@ import { trustedIpDALFactory } from "@app/ee/services/trusted-ip/trusted-ip-dal"
import { trustedIpServiceFactory } from "@app/ee/services/trusted-ip/trusted-ip-service";
import { keyValueStoreDALFactory } from "@app/keystore/key-value-store-dal";
import { TKeyStoreFactory } from "@app/keystore/keystore";
+import { ApiDocsTags } from "@app/lib/api-docs";
import { getConfig, TEnvConfig } from "@app/lib/config/env";
import { cronJobFactory } from "@app/lib/cron/cron-job";
import { crypto } from "@app/lib/crypto/cryptography";
@@ -4488,6 +4489,11 @@ export const registerRoutes = async (
rateLimit: readLimit
},
schema: {
+ hide: false,
+ operationId: "getInstanceStatus",
+ tags: [ApiDocsTags.Instance],
+ description:
+ "Get the status of the Infisical instance and the features configured on it. Public and unauthenticated; used by liveness and readiness probes and exempt from the API-wide rate limit.",
response: {
200: z.object({
date: z.date(),
diff --git a/backend/src/server/routes/v1/identity-router.ts b/backend/src/server/routes/v1/identity-router.ts
index f846a4d249..d78d4ae98b 100644
--- a/backend/src/server/routes/v1/identity-router.ts
+++ b/backend/src/server/routes/v1/identity-router.ts
@@ -530,7 +530,16 @@ export const registerIdentityRouter = async (server: FastifyZodProvider) => {
rateLimit: readLimit
},
schema: {
+ hide: false,
operationId: "getMachineIdentityDetails",
+ tags: [ApiDocsTags.Identities],
+ description:
+ "Get details for the calling machine identity, including the organization it belongs to. Called with the identity's own access token.",
+ security: [
+ {
+ bearerAuth: []
+ }
+ ],
response: {
200: z.object({
identityDetails: z.object({
diff --git a/docs/api-reference/endpoints/identities/details.mdx b/docs/api-reference/endpoints/identities/details.mdx
new file mode 100644
index 0000000000..c22c2baff0
--- /dev/null
+++ b/docs/api-reference/endpoints/identities/details.mdx
@@ -0,0 +1,4 @@
+---
+title: "Get details"
+openapi: "GET /api/v1/identities/details"
+---
diff --git a/docs/api-reference/endpoints/instance/status.mdx b/docs/api-reference/endpoints/instance/status.mdx
new file mode 100644
index 0000000000..3bc7e7c631
--- /dev/null
+++ b/docs/api-reference/endpoints/instance/status.mdx
@@ -0,0 +1,4 @@
+---
+title: "Get status"
+openapi: "GET /api/status"
+---
diff --git a/docs/api-reference/overview/authentication.mdx b/docs/api-reference/overview/authentication.mdx
index ef54fb933e..841a63a3b3 100644
--- a/docs/api-reference/overview/authentication.mdx
+++ b/docs/api-reference/overview/authentication.mdx
@@ -1,28 +1,92 @@
---
title: "Authentication"
-description: "Learn how to authenticate with the Infisical Public API."
+description: "Log in as a machine identity and use the returned access token on every Infisical API request."
---
-You can authenticate with the Infisical API using [Identities](/documentation/platform/identities/machine-identities) paired with authentication modes such as [Universal Auth](/documentation/platform/identities/universal-auth).
+To call the Infisical API, you need to authenticate as a [machine identity](/documentation/platform/identities/machine-identities) using one of the authentication methods listed below. The authentication method returns a short-lived access token. Include that token as an `Authorization: Bearer <token>` header on every Infisical API request.
+<Note>
+ For a guide on authenticating with Universal Auth and calling the API, check out the [Quickstart](/api-reference/overview/quickstart).
+</Note>
-To interact with the Infisical API, you'll need to obtain an access token. Follow the step by [step guide](/documentation/platform/identities/universal-auth) to get an access token via Universal Auth.
+## Authentication methods
+Each authentication method accepts a different type of credential:
-**FAQ**
+### Infisical-issued credentials
+
+These methods accept credentials that Infisical creates and manages directly, such as a client ID and client secret or a long-lived access token. They work from any environment.
+
+<CardGroup cols={2}>
+ <Card title="Universal Auth" href="/documentation/platform/identities/universal-auth">
+ Authenticate with a client ID and client secret.
+ </Card>
+ <Card title="Token Auth" href="/documentation/platform/identities/token-auth">
+ Authenticate with a long-lived, manually issued access token.
+ </Card>
+</CardGroup>
+
+### Cloud providers
+
+Cloud providers accept the identity the calling workload already has on that cloud, such as an IAM role, a managed identity, or a service account.
+
+<CardGroup cols={2}>
+ <Card title="AWS Auth" href="/documentation/platform/identities/aws-auth">
+ Authenticate from an EC2 instance, ECS task, Lambda function, or any AWS workload with an IAM role.
+ </Card>
+ <Card title="Azure Auth" href="/documentation/platform/identities/azure-auth">
+ Authenticate from an Azure workload with a managed identity.
+ </Card>
+ <Card title="GCP Auth" href="/documentation/platform/identities/gcp-auth">
+ Authenticate from a Compute Engine instance, GKE pod, or Cloud Run service using its GCP service account.
+ </Card>
+ <Card title="Kubernetes Auth" href="/documentation/platform/identities/kubernetes-auth">
+ Authenticate from a Kubernetes pod using its service account token.
+ </Card>
+ <Card title="OCI Auth" href="/documentation/platform/identities/oci-auth">
+ Authenticate from an Oracle Cloud compute instance using its instance principal.
+ </Card>
+ <Card title="AliCloud Auth" href="/documentation/platform/identities/alicloud-auth">
+ Authenticate from an Alibaba Cloud workload using an assumed RAM role.
+ </Card>
+</CardGroup>
+
+### External identity
+
+These methods accept a credential from a trusted external system, such as an OIDC identity token, a JWT signed by a trusted issuer, an LDAP bind, a client certificate, or a SPIFFE SVID.
+
+<CardGroup cols={2}>
+ <Card title="OIDC Auth" href="/documentation/platform/identities/oidc-auth/general">
+ Authenticate with an OIDC identity token from a trusted OIDC provider.
+ </Card>
+ <Card title="JWT Auth" href="/documentation/platform/identities/jwt-auth">
+ Authenticate with a JWT signed by a trusted issuer.
+ </Card>
+ <Card title="LDAP Auth" href="/documentation/platform/identities/ldap-auth/general">
+ Authenticate against a configured LDAP directory.
+ </Card>
+ <Card title="TLS certificate Auth" href="/documentation/platform/identities/tls-cert-auth">
+ Authenticate with a client certificate signed by a trusted certificate authority.
+ </Card>
+ <Card title="SPIFFE Auth" href="/documentation/platform/identities/spiffe-auth">
+ Authenticate with a SPIFFE SVID from a workload attested by SPIRE.
+ </Card>
+</CardGroup>
+
+## FAQ
<AccordionGroup>
-<Accordion title="Why can I not create, read, update, or delete an identity?">
- There are a few reasons for why this might happen:
-
- - You have insufficient organization permissions to create, read, update, delete identities.
- - The identity you're trying to read, update, or delete is more privileged than yourself.
- - The role you're trying to create an identity for or update an identity to is more privileged than yours.
-</Accordion>
-<Accordion title="Why is the Infisical API rejecting my identity credentials?">
- There are a few reasons for why this might happen:
-
- - The client secret or access token has expired.
- - The identity is insufficiently permissioned to interact with the resources you wish to access.
- - The client secret/access token is being used from an untrusted IP.
-</Accordion>
+ <Accordion title="Why can I not create, read, update, or delete an identity?">
+ A few reasons this can happen:
+
+ - The calling identity doesn't have the org permissions required to manage identities
+ - The identity being changed is more privileged than the calling identity
+ - The role being assigned is more privileged than any role held by the calling identity
+ </Accordion>
+ <Accordion title="Why is the Infisical API rejecting my identity credentials?">
+ A few reasons this can happen:
+
+ - The client secret or access token has expired
+ - The identity doesn't have the permissions required by the endpoint
+ - The client secret or access token is being used from an IP address the identity doesn't trust
+ </Accordion>
</AccordionGroup>
diff --git a/docs/api-reference/overview/errors.mdx b/docs/api-reference/overview/errors.mdx
new file mode 100644
index 0000000000..ce3f2382ec
--- /dev/null
+++ b/docs/api-reference/overview/errors.mdx
@@ -0,0 +1,62 @@
+---
+title: "Errors"
+description: "The Infisical API error response format, common HTTP status codes, and how to use the request ID when reporting an issue."
+---
+
+Most error responses from the Infisical API share a standard JSON schema with four fields: the HTTP status, a short machine-readable identifier, a human-readable message, and a request identifier. A few protocol-specific endpoints return [their protocol's own error shape](#protocol-specific-error-shapes) instead.
+
+## Response format
+
+```json
+{
+ "reqId": "req-abc123",
+ "statusCode": 404,
+ "message": "Project with ID 'ba3d4bfc-...' not found",
+ "error": "NotFound"
+}
+```
+
+The standard response schema contains these four fields:
+
+- `reqId`: the identifier assigned to this request by the Infisical server; include it when [reporting an issue](#reporting-an-issue)
+- `statusCode`: the HTTP status code, also included in the response body for logging
+- `error`: a short, stable identifier for the error class that can be used to branch application logic (for example, `NotFound`, `BadRequest`, `ValidationFailure`, `PermissionDenied`, `RateLimitExceeded`)
+- `message`: a description of the error, usually a string; on a `ValidationFailure` returned by request-body schema validation, it can be an array of individual field-level errors instead
+
+Some responses also include an optional `details` field with additional structured information about the error (for example, the input value that failed validation, or the permission that was denied). The presence and structure of `details` depend on the specific error.
+
+## Protocol-specific error shapes
+
+A few endpoints implement well-known protocols and return the error shape those protocols define:
+
+- **OAuth 2.0 token endpoints** (for example, `POST /api/v1/oauth/token`) return `{ error, error_description }` per [RFC 6749 §5.2](https://datatracker.ietf.org/doc/html/rfc6749#section-5.2)
+- **SCIM endpoints** (`/api/v1/scim/...`) return the SCIM error object (`schemas`, `status`, `detail`, `scimType`) per [RFC 7644 §3.12](https://datatracker.ietf.org/doc/html/rfc7644#section-3.12)
+- **ACME endpoints** (`/api/v1/pki/acme/...`) return `application/problem+json` per [RFC 8555 §6.7](https://datatracker.ietf.org/doc/html/rfc8555#section-6.7)
+
+## Common status codes
+
+Here are some common error codes returned by the API:
+
+| Status | `error` value | Meaning |
+| --- | --- | --- |
+| 400 | `BadRequest` | The request was well-formed but rejected by a semantic check. The `message` describes what to change. |
+| 401 | `UnauthorizedError` | The access token is missing, expired, or invalid. Re-authenticate to get a new access token. |
+| 403 | `PermissionDenied` or `ForbiddenError` | The identity is authenticated but doesn't have a role or permission that this endpoint requires. |
+| 404 | `NotFound` | The requested resource doesn't exist, or the identity doesn't have access to it. Infisical returns `404` (rather than `403`) for resources outside the identity's scope so that the API can't be used to confirm the existence of another tenant's resources. |
+| 409 | `Conflict` | The request conflicts with the current state of the resource (for example, a duplicate name, or a state transition that isn't allowed). |
+| 422 | `ValidationFailure` | A field in the request failed schema validation. The `message` field usually contains an array of individual field-level errors. |
+| 429 | `RateLimitExceeded` | The applicable [rate limit](/api-reference/overview/rate-limits) has been exceeded. The `message` field indicates the number of seconds to wait before retrying. |
+| 500 | `InternalServerError` | An unexpected error on the Infisical server. Include the `reqId` when reporting the error. |
+| 504 | `GatewayTimeoutError` | An upstream dependency (for example, a database, an external KMS, or a gateway target) didn't respond within the configured timeout. Retrying the request is usually safe. |
+
+Retry a `429` response after the wait time indicated in the `message` field. For a `5xx` response, retry idempotent requests (`GET`, `PUT`, `DELETE`) with exponential backoff. Don't blindly retry a `POST` or `PATCH` on a `5xx`, since the server may have completed the write before the response failed; retry only if the endpoint documents an idempotency mechanism or you can verify the operation didn't take effect. Don't retry a `4xx` response other than `429` without changing the request first.
+
+## Reporting an issue
+
+When reporting an issue, include:
+
+- The `reqId` from the response
+- The HTTP status code and the `error` value
+- The endpoint that was called and the approximate time of the call
+
+The `reqId` contains no credentials or user data and is safe to share in tickets, chat messages, and public issue trackers.
diff --git a/docs/api-reference/overview/introduction.mdx b/docs/api-reference/overview/introduction.mdx
index acb85d4e5d..c080a2be4e 100644
--- a/docs/api-reference/overview/introduction.mdx
+++ b/docs/api-reference/overview/introduction.mdx
@@ -1,51 +1,51 @@
---
title: "API reference"
-description: "Programmatically manage secrets, access control, and audit logs over HTTPS with the Infisical REST API."
+description: "Programmatically manage resources over HTTPS with the Infisical REST API."
sidebarTitle: "API"
icon: "book-open"
---
-Infisical's Public (REST) API provides users an alternative way to programmatically access and manage
-secrets via HTTPS requests. This can be useful for automating tasks, such as
-rotating credentials, or for integrating secret management into a larger system.
+The Infisical API is a REST API served over HTTPS. It supports every action available in the Infisical dashboard: reading and writing secrets, managing projects and machine identities, reading audit logs, and configuring the other resources in an organization.
-With the Public API, you can create, read, update, and delete secrets, as well as manage access control, query audit logs, and more.
+<Card title="Quickstart" icon="rocket" href="/api-reference/overview/quickstart">
+ Make your first authenticated request to the Infisical API using Universal Auth.
+</Card>
+
+<Tip>
+ You can also interact with Infisical programmatically using the [CLI](/cli/overview) and [SDKs](/sdks/overview).
+</Tip>
+
+## Base URL
+
+If you use Infisical Cloud, all endpoints are available under `https://app.infisical.com/api` (US region) or `https://eu.infisical.com/api` (EU region).
+
+If you self-host Infisical or run a dedicated instance, replace the host with the address of your instance: `https://<your-instance>/api`.
+
+Each endpoint page in this reference lists a path (for example, `/api/v3/secrets/raw`). The full URL for a request is the base URL followed by that path.
## API versioning
-The API is versioned on a per-resource basis. A resource's version is only incremented for breaking changes, so different endpoints may have different version numbers (e.g., `/api/v4/secrets` vs. `/api/v1/secret-syncs`).
-
-As a best practice, always use the latest available version for each endpoint to ensure access to the most recent features and improvements.
-
-## Rate limits
-
-Infisical enforces several different types of rate limits:
-
-- **Read**: For GET and LIST operations.
-- **Write**: For CREATE, UPDATE, and DELETE operations.
-- **Secret**: Specifically for secret management operations such as getting and creating secrets.
-- **Identity Creation**: For creating new identities within an organization.
-- **Project Creation**: For creating new projects within an organization.
-
-**Self-hosted** instances have no limits, these limits apply only to **Infisical Cloud**.
-
-<Tabs>
- <Tab title="Free Plan">
- - **Read**: 200/minute
- - **Write**: 90/minute
- - **Secret**: 120/minute
- - **Identity Creation**: 30/minute
- - **Project Creation**: 30/minute
- </Tab>
- <Tab title="Pro Plan">
- - **Read**: 350/minute
- - **Write**: 200/minute
- - **Secret**: 300/minute
- - **Identity Creation**: 30/minute
- - **Project Creation**: 30/minute
- </Tab>
-</Tabs>
-
-<Note>
- Custom rate limits are available for Enterprise customers. If you need higher rate limits, please contact [email protected].
-</Note>
+Each endpoint path is versioned independently. When an endpoint changes in a way that breaks existing callers, Infisical adds a new version of that endpoint and leaves the previous version in place. Different endpoints can therefore be on different versions (for example, `/api/v4/secrets` and `/api/v1/secret-syncs`).
+
+For each endpoint, use the highest version listed in this reference.
+
+## OpenAPI
+
+Every running Infisical instance serves its OpenAPI specification at `/api/docs/json` (on Infisical Cloud, `https://app.infisical.com/api/docs/json`). Code generators and client libraries can read the specification from that URL to produce typed clients for any endpoint in this reference.
+
+## Get started
+
+<CardGroup cols={2}>
+ <Card title="Authentication" icon="key" href="/api-reference/overview/authentication">
+ Authenticate as a machine identity and use the returned access token on every request.
+ </Card>
+ <Card title="Pagination" icon="list" href="/api-reference/overview/pagination">
+ Use `offset` and `limit` to read all pages from a paginated endpoint.
+ </Card>
+ <Card title="Rate limiting" icon="gauge-high" href="/api-reference/overview/rate-limits">
+ Per-minute rate limits by category, and the format of the HTTP 429 response.
+ </Card>
+ <Card title="Errors" icon="triangle-exclamation" href="/api-reference/overview/errors">
+ The format of an error response, the common HTTP status codes, and the `reqId` field.
+ </Card>
+</CardGroup>
diff --git a/docs/api-reference/overview/pagination.mdx b/docs/api-reference/overview/pagination.mdx
new file mode 100644
index 0000000000..509df25259
--- /dev/null
+++ b/docs/api-reference/overview/pagination.mdx
@@ -0,0 +1,59 @@
+---
+title: "Pagination"
+description: "Learn how to paginate through responses returned by the Infisical API."
+---
+
+Endpoints that return multiple items paginate their responses. Each response contains one page of items and a `totalCount` field with the total number of matching items across all pages.
+
+## Parameters
+
+Paginated endpoints accept two parameters:
+
+- `offset`: the number of items to skip before returning results (defaults to `0`)
+- `limit`: the maximum number of items to return in one page (defaults vary by endpoint, commonly `20` or `50`, with a maximum typically of `100`)
+
+Depending on the endpoint, `offset` and `limit` are either passed as query string parameters on a `GET` request or included in the request body of a `POST` request. Each endpoint's reference page lists the accepted range and the exact location for both parameters.
+
+## Ordering
+
+Endpoints that support ordering accept two additional parameters:
+
+- `orderBy`: the field to sort by (accepted values are listed on the endpoint's reference page)
+- `orderDirection`: `asc` for ascending or `desc` for descending (defaults to `asc`)
+
+## Response format
+
+A paginated response contains a `totalCount` field with the total number of matching items across all pages, and an array of items for the current page. The array is nested under a field named after the resource (for example, `identities`, `groups`, or `certificates`):
+
+```json
+{
+ "identities": [
+ { "id": "...", "name": "..." }
+ ],
+ "totalCount": 132
+}
+```
+
+To read every page, start at `offset = 0` and increase `offset` by `limit` on each following request. Stop when the running count of items read reaches `totalCount`.
+
+## Example
+
+The following request reads machine identities in an organization, 50 at a time, sorted by name:
+
+```bash
+curl -X POST https://app.infisical.com/api/v2/identities/search \
+ -H "Authorization: Bearer <your-access-token>" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "limit": 50,
+ "offset": 0,
+ "orderBy": "name",
+ "orderDirection": "asc"
+ }'
+```
+
+To read the second page, send the same request with `offset` set to `50`.
+
+## Endpoints without pagination
+
+Some endpoints return their entire result in a single response without paginating. For example, `GET /api/v4/secrets` returns all secrets in the specified project, environment, and folder path. Each endpoint's reference page indicates whether pagination applies.
diff --git a/docs/api-reference/overview/quickstart.mdx b/docs/api-reference/overview/quickstart.mdx
new file mode 100644
index 0000000000..b902df4fe7
--- /dev/null
+++ b/docs/api-reference/overview/quickstart.mdx
@@ -0,0 +1,128 @@
+---
+title: "Quickstart"
+description: "Create a machine identity, authenticate with Universal Auth, and make your first request to the Infisical API."
+---
+
+This quickstart creates a machine identity with Universal Auth credentials and uses those credentials to make an authenticated request to the Infisical API.
+
+<Note>
+ This quickstart uses [Universal Auth](/documentation/platform/identities/universal-auth). For the full list of authentication methods and when to pick each one, see [Authentication](/api-reference/overview/authentication).
+</Note>
+
+## Prerequisites
+
+- The [Admin role](/documentation/platform/access-controls/role-based-access-controls) on either your Infisical organization or a project in the organization
+
+## Step 1: Create a machine identity
+
+You can create a machine identity at the organization level or scoped to a single project. The rest of the quickstart works the same either way.
+
+<Tabs>
+ <Tab title="Organization-level">
+ <Steps>
+ <Step>
+ In your organization, go to **Access Control** > **Machine Identities**, then select **Create**.
+ </Step>
+ <Step>
+ Enter a **Name** for the identity, pick an organization **Role** (**Admin** or **Member** are both fine for this guide), and select **Create**.
+ </Step>
+ </Steps>
+ </Tab>
+ <Tab title="Project-level">
+ <Steps>
+ <Step>
+ Open the project, go to **Access Control** > **Machine Identities**, then select **Add Machine Identity to Project**.
+ </Step>
+ <Step>
+ On the **Create New** tab, enter a **Name**, pick a project **Role**, and select **Create**.
+ </Step>
+ </Steps>
+ </Tab>
+</Tabs>
+
+This creates the identity with Universal Auth enabled by default and opens the identity's details page.
+
+## Step 2: Generate a client secret
+
+Universal Auth uses a **Client ID** and **Client Secret** pair. Infisical creates the Client ID with the identity but issues each Client Secret on demand.
+
+<Steps>
+ <Step>
+ On the identity's details page, in the **Authentication** card, select the **Universal Auth** row.
+ </Step>
+ <Step>
+ In the sheet that opens, copy the **Client ID**.
+ </Step>
+ <Step>
+ Select **Add Client Secret**, then **Create** to generate a new secret.
+ </Step>
+</Steps>
+
+<Warning>
+ Infisical shows the Client Secret only once. Copy it now and store it somewhere safe before closing the dialog.
+</Warning>
+
+## Step 3: Exchange the credentials for an access token
+
+Call [the login endpoint for Universal Auth](/api-reference/endpoints/universal-auth/login) with the Client ID and Client Secret in the request body:
+
+```bash
+curl -X POST https://app.infisical.com/api/v1/auth/universal-auth/login \
+ -H "Content-Type: application/json" \
+ -d '{
+ "clientId": "<your-client-id>",
+ "clientSecret": "<your-client-secret>"
+ }'
+```
+
+The response contains the access token, the token's remaining lifetime in seconds (`expiresIn`), and the maximum lifetime the token can reach with renewals (`accessTokenMaxTTL`):
+
+```json
+{
+ "accessToken": "st.xxxxxxxxxxxxxxxxxxxxxxxx",
+ "expiresIn": 7200,
+ "accessTokenMaxTTL": 43200,
+ "tokenType": "Bearer"
+}
+```
+
+## Step 4: Call the API with the access token
+
+Include the access token as an `Authorization: Bearer` header on every request. For example, to [look up the identity's own details](/api-reference/endpoints/identities/details):
+
+```bash
+curl https://app.infisical.com/api/v1/identities/details \
+ -H "Authorization: Bearer <your-access-token>"
+```
+
+The response returns the organization the identity belongs to:
+
+```json
+{
+ "identityDetails": {
+ "organization": {
+ "id": "...",
+ "name": "...",
+ "slug": "..."
+ }
+ }
+}
+```
+
+Every endpoint in this reference accepts the same `Authorization` header format.
+
+<Check>
+ You can now make authenticated calls to the Infisical API.
+</Check>
+
+## Next steps
+
+To call an endpoint that operates on a project's resources (for example, reading secrets, issuing certificates, or managing PAM resources), the identity needs to be a member of that project.
+
+If you create the machine identity at the organization-level, it needs to be added to each project you want it to reach. You can do this from **Access Control** > **Machine Identities** inside the project itself.
+
+For more information, check out the machine identity docs:
+
+<Card title="Machine identities" icon="id-card" href="/documentation/platform/identities/machine-identities">
+ How machine identities work, including scopes, project membership, roles, credential rotation, and alerts.
+</Card>
diff --git a/docs/api-reference/overview/rate-limits.mdx b/docs/api-reference/overview/rate-limits.mdx
new file mode 100644
index 0000000000..d3ce3e6715
--- /dev/null
+++ b/docs/api-reference/overview/rate-limits.mdx
@@ -0,0 +1,63 @@
+---
+title: "Rate limiting"
+description: "Learn how Infisical Cloud enforces rate limits on API requests."
+---
+
+Infisical Cloud enforces per-minute rate limits on API requests. A global cap of 600 requests per minute per client IP applies to every endpoint (the [status endpoint](/api-reference/endpoints/instance/status) is exempt). On top of that, category-specific limits are tracked separately per client IP address.
+
+## Categories
+
+Each API request is counted against one of the following categories:
+
+- **Read**: read operations
+- **Write**: create, update, and delete operations
+- **Secret**: secret management operations (for example, reading or creating a secret)
+- **Identity creation**: creating a new machine identity in an organization
+- **Project creation**: creating a new project in an organization
+
+## Limits on Infisical Cloud
+
+ A global cap of 600 requests per minute per client IP applies to every endpoint (except the [status endpoint](/api-reference/endpoints/instance/status)). On top of that, category-specific limits are tracked separately per client IP address.
+
+ The per-category limits by plan on Infisical Cloud are:
+
+<Tabs>
+ <Tab title="Free">
+ - **Read**: 200 per minute
+ - **Write**: 90 per minute
+ - **Secret**: 120 per minute
+ - **Identity creation**: 30 per minute
+ - **Project creation**: 30 per minute
+ </Tab>
+ <Tab title="Pro">
+ - **Read**: 350 per minute
+ - **Write**: 200 per minute
+ - **Secret**: 300 per minute
+ - **Identity creation**: 30 per minute
+ - **Project creation**: 30 per minute
+ </Tab>
+</Tabs>
+
+<Note>
+ Enterprise plans on Infisical Cloud can get higher custom rate limits. Contact
+ [email protected] for details.
+</Note>
+
+## Limits on self-hosted instances
+
+If you self-host Infisical, no rate limits are enforced on the API by default. If you need throttling on your API surface, you'll need to configure an external rate limiter.
+
+## Exceeding rate limits (429 response)
+
+A request that exceeds the applicable limit returns HTTP `429` with the standard [error response](/api-reference/overview/errors):
+
+```json
+{
+ "reqId": "req-abc123",
+ "statusCode": 429,
+ "message": "Rate limit exceeded. Please try again in 42 seconds",
+ "error": "RateLimitExceeded"
+}
+```
+
+The `message` field includes the number of seconds remaining in the current rate limit window. Wait at least that long before resending the request.
diff --git a/docs/docs.json b/docs/docs.json
index eb85270be2..9ffa633b3c 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -1352,9 +1352,13 @@
"pages": [
"api-reference/overview/introduction",
{
- "group": "Overview",
+ "group": "Get started",
"pages": [
- "api-reference/overview/authentication"
+ "api-reference/overview/quickstart",
+ "api-reference/overview/authentication",
+ "api-reference/overview/pagination",
+ "api-reference/overview/rate-limits",
+ "api-reference/overview/errors"
]
},
{
@@ -1396,6 +1400,7 @@
"api-reference/endpoints/identities/update",
"api-reference/endpoints/identities/delete",
"api-reference/endpoints/identities/get-by-id",
+ "api-reference/endpoints/identities/details",
"api-reference/endpoints/identities/list",
"api-reference/endpoints/identities/search",
"api-reference/endpoints/identities/search-count",
@@ -4533,6 +4538,12 @@
"pages": [
"api-reference/endpoints/admin/bootstrap-instance"
]
+ },
+ {
+ "group": "Instance",
+ "pages": [
+ "api-reference/endpoints/instance/status"
+ ]
}
]
}
diff --git a/docs/documentation/getting-started/quickstarts.mdx b/docs/documentation/getting-started/quickstarts.mdx
index 9af0209cff..53c783438f 100644
--- a/docs/documentation/getting-started/quickstarts.mdx
+++ b/docs/documentation/getting-started/quickstarts.mdx
@@ -25,6 +25,7 @@ mode: "frame"
<a href="#identity-and-access" className="qs-index__jump-chip qs-index__jump-chip--identity">Identity</a>
<a href="#networking" className="qs-index__jump-chip qs-index__jump-chip--networking">Networking</a>
<a href="#self-hosting" className="qs-index__jump-chip qs-index__jump-chip--self-hosting">Self-hosting</a>
+ <a href="#api-reference" className="qs-index__jump-chip qs-index__jump-chip--api">API reference</a>
</div>
</div>
@@ -162,4 +163,16 @@ mode: "frame"
</section>
+<section className="qs-index__section qs-index__section--api">
+
+<h2 id="api-reference"><a href="/api-reference/overview/introduction" className="qs-index__section-link">API reference<svg className="qs-index__section-arrow" width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true"><path d="m9 18 6-6-6-6" /></svg></a></h2>
+
+<p className="qs-index__section-desc">Programmatically manage resources over HTTPS with the Infisical REST API.</p>
+
+| Quickstart | Description |
+| --- | --- |
+| [Make your first authenticated API request](/api-reference/overview/quickstart) | Create a machine identity, authenticate with Universal Auth, and call the Infisical API. |
+
+</section>
+
</div>
diff --git a/docs/style.css b/docs/style.css
index 62ca549b19..9622f04959 100644
--- a/docs/style.css
+++ b/docs/style.css
@@ -92,6 +92,7 @@
.qs-index__jump-chip--identity { --qs-chip-color: #cfcfcf; }
.qs-index__jump-chip--networking { --qs-chip-color: #cfcfcf; }
.qs-index__jump-chip--self-hosting { --qs-chip-color: #cfcfcf; }
+.qs-index__jump-chip--api { --qs-chip-color: #cfcfcf; }
.qs-index__jump-chip:hover {
border-color: var(--qs-chip-color, #cfcfcf);
@@ -122,6 +123,7 @@
.dark .qs-index__jump-chip--identity { --qs-chip-color: #3a3f47; }
.dark .qs-index__jump-chip--networking { --qs-chip-color: #3a3f47; }
.dark .qs-index__jump-chip--self-hosting { --qs-chip-color: #3a3f47; }
+.dark .qs-index__jump-chip--api { --qs-chip-color: #3a3f47; }
.dark .qs-index__jump-chip:hover {
border-color: var(--qs-chip-color, #3a3f47);
@@ -140,7 +142,8 @@
.qs-index__section--agent-vault { --qs-accent: #5f7000; }
.qs-index__section--identity,
.qs-index__section--networking,
-.qs-index__section--self-hosting {
+.qs-index__section--self-hosting,
+.qs-index__section--api {
--qs-accent: #5c5c5c;
}
@@ -266,7 +269,8 @@
.dark .qs-index__section--agent-vault { --qs-accent: #a1d434; }
.dark .qs-index__section--identity,
.dark .qs-index__section--networking,
-.dark .qs-index__section--self-hosting {
+.dark .qs-index__section--self-hosting,
+.dark .qs-index__section--api {
--qs-accent: #cfcfcf;
}