Infisical is the open-source platform for securing secrets, certificates, access, and AI Agents.
TypeScript acmeagentsai-agentscertificate-managementdevsecopsenvironment-variableskubernetesopen-sourcepampkipostgresprivate-caprivileged-access-managementsecret-managementsecret-managersecretssecrets-managementsecuritysecurity-toolsvault
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.tsindex 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.tsindex 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.tsindex 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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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.mdxindex 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.mdxnew file mode 100644index 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.mdxindex 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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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.jsonindex 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.mdxindex 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.cssindex 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;}