Gabriel Brown
89761a7da3
Agent instructions, skills, SSH host aliases and expansion triggers are worth having identical on every machine one person owns, and belong in none of the shared configuration. They live in user/ now, with a manifest saying where each piece goes and a link-user stage that puts it there. That stage does nothing unless the machine said yes. Somebody who clones Panama to try the desktop keeps their own ~/.claude/CLAUDE.md exactly where it was; the question names the destinations and defaults to no. Anything displaced goes to config/old rather than being deleted. ~/.claude/CLAUDE.md and ~/.codex/AGENTS.md were byte-identical copies of one file, which is the drift this exists to prevent. Also adds the vitals toggles for the battery and Claude usage readouts, which had preferences and no way to reach them.
497 lines
8.7 KiB
Markdown
497 lines
8.7 KiB
Markdown
# Projects and Identities
|
|
|
|
## Projects
|
|
|
|
Projects are containers for secrets, environments, and team members. Always use `/api/v1/projects` (not the deprecated `/api/v1/workspace`).
|
|
|
|
### List Projects
|
|
|
|
#### Endpoint
|
|
|
|
```
|
|
GET /api/v1/projects
|
|
```
|
|
|
|
#### Query Parameters
|
|
|
|
| Parameter | Type | Default | Max | Description |
|
|
|-----------|------|---------|-----|-------------|
|
|
| offset | integer | 0 | - | Number of items to skip |
|
|
| limit | integer | 20 | 100 | Number of items to return |
|
|
|
|
#### Response
|
|
|
|
```json
|
|
{
|
|
"projects": [
|
|
{
|
|
"id": "project-id-uuid",
|
|
"name": "My Project",
|
|
"slug": "my-project",
|
|
"createdAt": "2026-04-01T10:00:00.000Z",
|
|
"updatedAt": "2026-04-16T10:30:00.000Z",
|
|
"version": 1
|
|
}
|
|
],
|
|
"total": 5
|
|
}
|
|
```
|
|
|
|
#### Example
|
|
|
|
```bash
|
|
curl -X GET 'https://us.infisical.com/api/v1/projects?offset=0&limit=20' \
|
|
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
|
|
```
|
|
|
|
### Get Project
|
|
|
|
#### Endpoint
|
|
|
|
```
|
|
GET /api/v1/projects/{projectId}
|
|
```
|
|
|
|
#### Response
|
|
|
|
```json
|
|
{
|
|
"project": {
|
|
"id": "project-id-uuid",
|
|
"name": "My Project",
|
|
"slug": "my-project",
|
|
"createdAt": "2026-04-01T10:00:00.000Z",
|
|
"updatedAt": "2026-04-16T10:30:00.000Z",
|
|
"version": 1,
|
|
"environments": [
|
|
{
|
|
"id": "env-id",
|
|
"name": "Development",
|
|
"slug": "dev",
|
|
"version": 1
|
|
},
|
|
{
|
|
"id": "env-id-2",
|
|
"name": "Production",
|
|
"slug": "prod",
|
|
"version": 1
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Example
|
|
|
|
```bash
|
|
curl -X GET 'https://us.infisical.com/api/v1/projects/abc123' \
|
|
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
|
|
```
|
|
|
|
### Create Project
|
|
|
|
#### Endpoint
|
|
|
|
```
|
|
POST /api/v1/projects
|
|
```
|
|
|
|
#### Request Body
|
|
|
|
```json
|
|
{
|
|
"name": "string",
|
|
"slug": "string (optional)"
|
|
}
|
|
```
|
|
|
|
#### Response
|
|
|
|
Returns the created project object.
|
|
|
|
#### Example
|
|
|
|
```bash
|
|
curl -X POST 'https://us.infisical.com/api/v1/projects' \
|
|
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"name": "New Project",
|
|
"slug": "new-project"
|
|
}'
|
|
```
|
|
|
|
### Update Project
|
|
|
|
#### Endpoint
|
|
|
|
```
|
|
PATCH /api/v1/projects/{projectId}
|
|
```
|
|
|
|
#### Request Body
|
|
|
|
```json
|
|
{
|
|
"name": "string (optional)",
|
|
"slug": "string (optional)"
|
|
}
|
|
```
|
|
|
|
#### Example
|
|
|
|
```bash
|
|
curl -X PATCH 'https://us.infisical.com/api/v1/projects/abc123' \
|
|
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"name": "Updated Project Name"
|
|
}'
|
|
```
|
|
|
|
### Delete Project
|
|
|
|
#### Endpoint
|
|
|
|
```
|
|
DELETE /api/v1/projects/{projectId}
|
|
```
|
|
|
|
#### Example
|
|
|
|
```bash
|
|
curl -X DELETE 'https://us.infisical.com/api/v1/projects/abc123' \
|
|
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
|
|
```
|
|
|
|
## Environments
|
|
|
|
Environments (dev, staging, prod) organize secrets by deployment target.
|
|
|
|
### List Project Environments
|
|
|
|
#### Endpoint
|
|
|
|
```
|
|
GET /api/v1/projects/{projectId}/environments
|
|
```
|
|
|
|
#### Response
|
|
|
|
```json
|
|
{
|
|
"environments": [
|
|
{
|
|
"id": "env-id-uuid",
|
|
"name": "Development",
|
|
"slug": "dev",
|
|
"version": 1
|
|
},
|
|
{
|
|
"id": "env-id-2",
|
|
"name": "Production",
|
|
"slug": "prod",
|
|
"version": 1
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
#### Example
|
|
|
|
```bash
|
|
curl -X GET 'https://us.infisical.com/api/v1/projects/abc123/environments' \
|
|
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
|
|
```
|
|
|
|
## Project Members
|
|
|
|
Manage who has access to a project and their role.
|
|
|
|
### List Project Members
|
|
|
|
#### Endpoint
|
|
|
|
```
|
|
GET /api/v1/projects/{projectId}/memberships
|
|
```
|
|
|
|
#### Query Parameters
|
|
|
|
| Parameter | Type | Default | Max |
|
|
|-----------|------|---------|-----|
|
|
| offset | integer | 0 | - |
|
|
| limit | integer | 20 | 100 |
|
|
|
|
#### Response
|
|
|
|
```json
|
|
{
|
|
"memberships": [
|
|
{
|
|
"id": "membership-id",
|
|
"projectId": "project-id",
|
|
"userId": "user-id",
|
|
"user": {
|
|
"id": "user-id",
|
|
"email": "[email protected]"
|
|
},
|
|
"role": "admin"
|
|
}
|
|
],
|
|
"total": 3
|
|
}
|
|
```
|
|
|
|
#### Example
|
|
|
|
```bash
|
|
curl -X GET 'https://us.infisical.com/api/v1/projects/abc123/memberships' \
|
|
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
|
|
```
|
|
|
|
## Machine Identities
|
|
|
|
Machine identities allow non-human accounts to authenticate and access secrets.
|
|
|
|
### List Identities
|
|
|
|
#### Endpoint
|
|
|
|
```
|
|
GET /api/v1/identities
|
|
```
|
|
|
|
#### Query Parameters
|
|
|
|
| Parameter | Type | Default | Max | Description |
|
|
|-----------|------|---------|-----|-------------|
|
|
| offset | integer | 0 | - | Number to skip |
|
|
| limit | integer | 20 | 100 | Number to return |
|
|
|
|
#### Response
|
|
|
|
```json
|
|
{
|
|
"identities": [
|
|
{
|
|
"id": "identity-id-uuid",
|
|
"name": "Production API",
|
|
"createdAt": "2026-04-01T10:00:00.000Z",
|
|
"updatedAt": "2026-04-16T10:30:00.000Z"
|
|
}
|
|
],
|
|
"total": 1
|
|
}
|
|
```
|
|
|
|
#### Example
|
|
|
|
```bash
|
|
curl -X GET 'https://us.infisical.com/api/v1/identities?offset=0&limit=20' \
|
|
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
|
|
```
|
|
|
|
### Get Identity
|
|
|
|
#### Endpoint
|
|
|
|
```
|
|
GET /api/v1/identities/{identityId}
|
|
```
|
|
|
|
#### Response
|
|
|
|
```json
|
|
{
|
|
"identity": {
|
|
"id": "identity-id-uuid",
|
|
"name": "Production API",
|
|
"universalAuthClientId": "machine-identity-uuid",
|
|
"createdAt": "2026-04-01T10:00:00.000Z",
|
|
"updatedAt": "2026-04-16T10:30:00.000Z"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Create Identity
|
|
|
|
#### Endpoint
|
|
|
|
```
|
|
POST /api/v1/identities
|
|
```
|
|
|
|
#### Request Body
|
|
|
|
```json
|
|
{
|
|
"name": "string"
|
|
}
|
|
```
|
|
|
|
### Update Identity
|
|
|
|
#### Endpoint
|
|
|
|
```
|
|
PATCH /api/v1/identities/{identityId}
|
|
```
|
|
|
|
#### Request Body
|
|
|
|
```json
|
|
{
|
|
"name": "string (optional)"
|
|
}
|
|
```
|
|
|
|
### Delete Identity
|
|
|
|
#### Endpoint
|
|
|
|
```
|
|
DELETE /api/v1/identities/{identityId}
|
|
```
|
|
|
|
## Identity Auth Methods
|
|
|
|
Configure how machine identities authenticate.
|
|
|
|
### Universal Auth (Recommended)
|
|
|
|
#### Endpoint
|
|
|
|
```
|
|
GET /api/v1/auth/universal-auth/identities/{identityId}
|
|
POST /api/v1/auth/universal-auth/identities/{identityId}
|
|
DELETE /api/v1/auth/universal-auth/identities/{identityId}
|
|
```
|
|
|
|
#### Example: Get Universal Auth Config
|
|
|
|
```bash
|
|
curl -X GET 'https://us.infisical.com/api/v1/auth/universal-auth/identities/identity-id' \
|
|
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
|
|
```
|
|
|
|
Response includes `clientId` and regenerated `clientSecret`.
|
|
|
|
#### AWS Auth
|
|
|
|
```
|
|
POST /api/v1/auth/aws-auth/identities/{identityId}
|
|
PATCH /api/v1/auth/aws-auth/identities/{identityId}
|
|
```
|
|
|
|
#### Azure Auth
|
|
|
|
```
|
|
POST /api/v1/auth/azure-auth/identities/{identityId}
|
|
PATCH /api/v1/auth/azure-auth/identities/{identityId}
|
|
```
|
|
|
|
#### GCP Auth
|
|
|
|
```
|
|
POST /api/v1/auth/gcp-auth/identities/{identityId}
|
|
PATCH /api/v1/auth/gcp-auth/identities/{identityId}
|
|
```
|
|
|
|
#### Kubernetes Auth
|
|
|
|
```
|
|
POST /api/v1/auth/kubernetes-auth/identities/{identityId}
|
|
PATCH /api/v1/auth/kubernetes-auth/identities/{identityId}
|
|
```
|
|
|
|
## Groups
|
|
|
|
Organize machine identities and manage permissions at scale.
|
|
|
|
### Endpoint
|
|
|
|
```
|
|
GET /api/v1/groups
|
|
POST /api/v1/groups
|
|
GET /api/v1/groups/{groupId}
|
|
PATCH /api/v1/groups/{groupId}
|
|
DELETE /api/v1/groups/{groupId}
|
|
```
|
|
|
|
### Example: List Groups
|
|
|
|
```bash
|
|
curl -X GET 'https://us.infisical.com/api/v1/groups' \
|
|
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
|
|
```
|
|
|
|
## Folders
|
|
|
|
Organize secrets into hierarchical folder structures.
|
|
|
|
### Endpoint
|
|
|
|
```
|
|
GET /api/v2/folders
|
|
POST /api/v2/folders
|
|
PATCH /api/v2/folders/{folderId}
|
|
DELETE /api/v2/folders/{folderId}
|
|
```
|
|
|
|
### List Folders
|
|
|
|
```bash
|
|
curl -X GET 'https://us.infisical.com/api/v2/folders?projectId=abc123&environment=dev' \
|
|
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
|
|
```
|
|
|
|
## Secret Imports
|
|
|
|
Import secrets from one environment into another.
|
|
|
|
### Endpoint
|
|
|
|
```
|
|
GET /api/v2/secret-imports
|
|
POST /api/v2/secret-imports
|
|
PATCH /api/v2/secret-imports/{importId}
|
|
DELETE /api/v2/secret-imports/{importId}
|
|
```
|
|
|
|
### Example: List Secret Imports
|
|
|
|
```bash
|
|
curl -X GET 'https://us.infisical.com/api/v2/secret-imports?projectId=abc123&environment=dev' \
|
|
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
|
|
```
|
|
|
|
## Deprecated Endpoints
|
|
|
|
**Do not use these endpoints in new code:**
|
|
|
|
- `/api/v1/workspace/*` — Use `/api/v1/projects` instead
|
|
- Service token endpoints — Use machine identities with Universal Auth instead
|
|
|
|
## Common Workflows
|
|
|
|
### Set Up a New Machine Identity
|
|
|
|
1. Create identity: `POST /api/v1/identities` → get `identityId`
|
|
2. Configure auth: `POST /api/v1/auth/universal-auth/identities/{identityId}`
|
|
3. Login: `POST /api/v1/auth/universal-auth/login` with `clientId` and `clientSecret`
|
|
4. Use returned `accessToken` for all subsequent API calls
|
|
|
|
### Add Identity to Project
|
|
|
|
1. Create identity and auth method (see above)
|
|
2. Create a folder/path in the target project
|
|
3. Create project membership or use RBAC rules to grant access
|
|
4. Test login with the new credentials
|
|
|
|
### Organize Secrets with Folders
|
|
|
|
1. Create folder: `POST /api/v2/folders` with `projectId`, `environment`, `folderName`
|
|
2. Create secrets under folder: `POST /api/v4/secrets/SECRET_NAME` with `secretPath: "/folder-name"`
|
|
3. List secrets in folder: `GET /api/v4/secrets?secretPath=/folder-name`
|