mirror of
https://github.com/awatertrevi/infisical.git
synced 2026-10-03 18:26:04 +00:00
Continue api-reference docs
This commit is contained in:
Tuan Dang
@@ -1,4 +1,4 @@
|
||||
---
|
||||
title: "Read"
|
||||
title: "Retrieve"
|
||||
openapi: "GET /api/v2/secrets/"
|
||||
---
|
||||
|
||||
@@ -0,0 +1,4 @@
|
||||
---
|
||||
title: "Get Current User"
|
||||
openapi: "GET /api/v2/users/me"
|
||||
---
|
||||
@@ -0,0 +1,4 @@
|
||||
---
|
||||
title: "Get Project Key"
|
||||
openapi: "GET /api/v2/workspace/{workspaceId}/encrypted-key"
|
||||
---
|
||||
@@ -1,3 +1,11 @@
|
||||
---
|
||||
title: "Authentication"
|
||||
---
|
||||
|
||||
To authenticate requests with Infisical, you must include an API key in the `X-API-KEY` header of HTTP requests made to the platform. You can obtain an API key from your user settings.
|
||||
|
||||
<Info>
|
||||
It's important to keep your API key secure, as it grants access to your
|
||||
secrets in Infisical. For added security, consider rotating your API key on a
|
||||
regular basis.
|
||||
</Info>
|
||||
|
||||
@@ -0,0 +1,64 @@
|
||||
---
|
||||
title: "Create secrets"
|
||||
---
|
||||
|
||||
In this example, we demonstrate how to add secrets to a project and environment.
|
||||
|
||||
Prerequisites:
|
||||
|
||||
- Set up and add envars to [Infisical Cloud](https://app.infisical.com)
|
||||
- Grasp a basic understanding of the system and its underlying cryptography [here](/api-reference/overview/introduction).
|
||||
|
||||
## Flow
|
||||
|
||||
1. Get your (encrypted) private key.
|
||||
2. Decrypt your (encrypted) private key with your password.
|
||||
3. Get the project key for the project.
|
||||
4. Decrypt the project key with your private key.
|
||||
5. Encrypt your secrets with the project key.
|
||||
6. Send (encrypted) secrets to the Infical API
|
||||
|
||||
## Example
|
||||
|
||||
```js
|
||||
const axios = require("axios");
|
||||
const aes = require("aes-256-gcm");
|
||||
const nacl = require("tweetnacl");
|
||||
nacl.util = require("tweetnacl-util");
|
||||
|
||||
const WORKSPACE_KEY = "3a7a243eb62078c13f09203e75e8cb32";
|
||||
|
||||
const secretKey = "SOME_KEY";
|
||||
const secretValue = "SOME_VALUE";
|
||||
|
||||
// encrypt key of secret
|
||||
const {
|
||||
ciphertext: secretKeyCiphertext,
|
||||
iv: secretKeyIV,
|
||||
tag: secretKeyTag,
|
||||
} = aes.encrypt(secretKey, WORKSPACE_KEY);
|
||||
|
||||
// encrypt value of secret
|
||||
const {
|
||||
ciphertext: secretValueCiphertext,
|
||||
iv: secretValueIV,
|
||||
tag: secretValueTag,
|
||||
} = aes.encrypt(secretKey, WORKSPACE_KEY);
|
||||
|
||||
// construct request body
|
||||
const secret = {
|
||||
secretKeyCiphertext,
|
||||
secretKeyIV,
|
||||
secretKeyTag,
|
||||
secretValueCiphertext,
|
||||
secretValueIV,
|
||||
secretValueTag,
|
||||
};
|
||||
```
|
||||
|
||||
<Info>
|
||||
This example uses [TweetNaCl.js](https://tweetnacl.js.org/#/), a port of
|
||||
TweetNacl/Nacl, to perform asymmeric decryption of the project key but there
|
||||
are ports of NaCl in every major language.
|
||||
|
||||
</Info>
|
||||
@@ -0,0 +1,10 @@
|
||||
---
|
||||
title: "Retrieve secrets"
|
||||
---
|
||||
|
||||
1. Get your (encrypted) private key.
|
||||
2. Decrypt your (encrypted) private key with your password.
|
||||
3. Get the project key for the project.
|
||||
4. Decrypt the project key with your private key.
|
||||
5. Get secrets for a project and environment.
|
||||
6. Decrypt the secrets in your project.
|
||||
@@ -0,0 +1,10 @@
|
||||
---
|
||||
title: "Update secrets"
|
||||
---
|
||||
|
||||
1. Get your (encrypted) private key.
|
||||
2. Decrypt your (encrypted) private key with your password.
|
||||
3. Get the project key for the project.
|
||||
4. Decrypt the project key with your private key.
|
||||
5. Encrypt your secrets with the project key.
|
||||
6. Send (encrypted) updated secrets to the Infical API
|
||||
@@ -1,3 +1,19 @@
|
||||
---
|
||||
title: "Introduction"
|
||||
---
|
||||
|
||||
Infisical's REST API provides users an alternative way to programmatically access and manage
|
||||
secrets via HTTP requests. This can be useful for automating tasks, such as
|
||||
rotating credentials, or for integrating secret management into a larger system.
|
||||
|
||||
With the REST API, users can create, read, update, and delete secrets, as well as manage access control, query audit logs, and more.
|
||||
|
||||
## Concepts
|
||||
|
||||
Using Infisical's API to manage secrets requires a basic understanding of the system and its underlying cryptography detailed [here](/security/overview).
|
||||
|
||||
- Each user has a public/private key pair that is stored with the platform; private keys are encrypted locally by the user's password before being sent off to the server during the account signup process.
|
||||
- Each (encrypted) secret belongs to a project and environment.
|
||||
- Each project has an (encrypted) project key used to encrypt the secrets within that project; Infisical stores copies of the project key, for each member of that project, encrypted under each member's public key.
|
||||
- Secrets are encrypted symmetrically by your copy of the project key belonging to the project containing.
|
||||
- Infisical uses AES256-GCM and [TweetNaCl.js](https://tweetnacl.js.org/#/) for symmetric and asymmetric encryption/decryption operations.
|
||||
|
||||
@@ -0,0 +1,18 @@
|
||||
---
|
||||
title: "Usage"
|
||||
---
|
||||
|
||||
Prerequisites:
|
||||
|
||||
- Set up and add envars to [Infisical Cloud](https://app.infisical.com) or your self-hosted instance.
|
||||
- Obtain an API Key in your user settings to be included in requests to the Infisical API.
|
||||
|
||||
Using Infisical's API to manage secrets requires a basic understanding of the system and its underlying cryptography detailed [here](/security/overview).
|
||||
|
||||
## Concepts
|
||||
|
||||
- Each user has a public/private key pair that is stored with the platform; private keys are encrypted locally by the user's password before being sent off to the server during the account signup process.
|
||||
- Each (encrypted) secret belongs to a project and environment.
|
||||
- Each project has an (encrypted) project key used to encrypt the secrets within that project; Infisical stores copies of the project key, for each member of that project, encrypted under each member's public key.
|
||||
- Secrets are encrypted symmetrically by your copy of the project key belonging to the project containing.
|
||||
- Infisical uses AES256-GCM and [TweetNaCl.js](https://tweetnacl.js.org/#/) for symmetric and asymmetric encryption/decryption operations.
|
||||
+31
-1
@@ -21,6 +21,16 @@
|
||||
"to": "#F8B7BD"
|
||||
}
|
||||
},
|
||||
"api": {
|
||||
"baseUrl": [
|
||||
"https://app.infisical.com",
|
||||
"http://localhost:8080"
|
||||
],
|
||||
"auth": {
|
||||
"method": "api-key",
|
||||
"name": "X-API-KEY"
|
||||
}
|
||||
},
|
||||
"topbarLinks": [
|
||||
{ "name": "Log In", "url": "https://app.infisical.com/login" }
|
||||
],
|
||||
@@ -134,12 +144,32 @@
|
||||
"group": "Overview",
|
||||
"pages": [
|
||||
"api-reference/overview/introduction",
|
||||
"api-reference/overview/authentication"
|
||||
"api-reference/overview/authentication",
|
||||
{
|
||||
"group": "Examples",
|
||||
"pages": [
|
||||
"api-reference/overview/examples/create-secrets",
|
||||
"api-reference/overview/examples/retrieve-secrets",
|
||||
"api-reference/overview/examples/update-secrets"
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Endpoints",
|
||||
"pages": [
|
||||
{
|
||||
"group": "Users",
|
||||
"pages": [
|
||||
"api-reference/endpoints/users/me"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Projects",
|
||||
"pages": [
|
||||
"api-reference/endpoints/workspaces/workspace-key"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Secrets",
|
||||
"pages": [
|
||||
|
||||
+291
-37
@@ -4,7 +4,10 @@ info:
|
||||
description: List of all available APIs that can be consumed
|
||||
version: 1.0.0
|
||||
servers:
|
||||
- url: https://infisical.com
|
||||
description: Production server
|
||||
- url: http://localhost:8080
|
||||
description: Local server
|
||||
paths:
|
||||
/api/v1/secret/{secretId}/secret-versions:
|
||||
get:
|
||||
@@ -1270,6 +1273,24 @@ paths:
|
||||
description: OK
|
||||
'400':
|
||||
description: Bad Request
|
||||
/api/v2/users/me:
|
||||
get:
|
||||
summary: Retrieve the current user on the request
|
||||
description: Retrieve the current user on the request
|
||||
parameters: []
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
$ref: '#/components/schemas/CurrentUser'
|
||||
description: Current user on request
|
||||
'400':
|
||||
description: Bad Request
|
||||
security:
|
||||
- apiKeyAuth: []
|
||||
/api/v2/workspace/{workspaceId}/secrets:
|
||||
post:
|
||||
description: ''
|
||||
@@ -1321,18 +1342,29 @@ paths:
|
||||
description: Bad Request
|
||||
/api/v2/workspace/{workspaceId}/encrypted-key:
|
||||
get:
|
||||
description: ''
|
||||
summary: Return encrypted project key
|
||||
description: Return encrypted project key
|
||||
parameters:
|
||||
- name: workspaceId
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
description: ID of project
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/ProjectKey'
|
||||
description: Encrypted project key for the given project
|
||||
'400':
|
||||
description: Bad Request
|
||||
security:
|
||||
- apiKeyAuth: []
|
||||
/api/v2/workspace/{workspaceId}/service-token-data:
|
||||
get:
|
||||
description: ''
|
||||
@@ -1513,57 +1545,122 @@ paths:
|
||||
example: any
|
||||
/api/v2/secrets/:
|
||||
post:
|
||||
description: ''
|
||||
summary: Create new secret(s)
|
||||
description: Create one or many secrets for a given project and environment.
|
||||
parameters: []
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/Secret'
|
||||
description: >-
|
||||
Array of newly-created secrets for the given project and
|
||||
environment
|
||||
security:
|
||||
- apiKeyAuth: []
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
secrets:
|
||||
example: any
|
||||
workspaceId:
|
||||
example: any
|
||||
type: string
|
||||
description: ID of project
|
||||
environment:
|
||||
example: any
|
||||
type: string
|
||||
description: Environment within project
|
||||
secrets:
|
||||
$ref: '#/components/schemas/CreateSecret'
|
||||
description: Secret(s) to create - object or array of objects
|
||||
get:
|
||||
description: ''
|
||||
parameters:
|
||||
- name: workspaceId
|
||||
in: query
|
||||
schema:
|
||||
type: string
|
||||
- name: environment
|
||||
in: query
|
||||
schema:
|
||||
type: string
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
patch:
|
||||
description: ''
|
||||
summary: Read secrets
|
||||
description: Read secrets from a project and environment
|
||||
parameters: []
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/Secret'
|
||||
description: Array of secrets for the given project and environment
|
||||
security:
|
||||
- apiKeyAuth: []
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
workspaceId:
|
||||
type: string
|
||||
description: ID of project
|
||||
environment:
|
||||
type: string
|
||||
description: Environment within project
|
||||
patch:
|
||||
summary: Update secret(s)
|
||||
description: Update secret(s)
|
||||
parameters: []
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/Secret'
|
||||
description: >-
|
||||
Array of newly-updated secrets for the given project and
|
||||
environment
|
||||
security:
|
||||
- apiKeyAuth: []
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
secrets:
|
||||
example: any
|
||||
$ref: '#/components/schemas/UpdateSecret'
|
||||
description: Secret(s) to update - object or array of objects
|
||||
delete:
|
||||
description: ''
|
||||
summary: Delete secret(s)
|
||||
description: Delete one or many secrets by their ID(s)
|
||||
parameters: []
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/Secret'
|
||||
description: Array of deleted secrets
|
||||
security:
|
||||
- apiKeyAuth: []
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
secretIds:
|
||||
type: string
|
||||
description: ID(s) of secrets - string or array of strings
|
||||
/api/v2/service-token/:
|
||||
get:
|
||||
description: ''
|
||||
@@ -1665,26 +1762,183 @@ paths:
|
||||
description: OK
|
||||
components:
|
||||
schemas:
|
||||
secret:
|
||||
CurrentUser:
|
||||
type: object
|
||||
properties:
|
||||
_id:
|
||||
type: string
|
||||
example: ''
|
||||
email:
|
||||
type: string
|
||||
example: ''
|
||||
firstName:
|
||||
type: string
|
||||
example: ''
|
||||
lastName:
|
||||
type: string
|
||||
example: ''
|
||||
publicKey:
|
||||
type: string
|
||||
example: ''
|
||||
encryptedPrivateKey:
|
||||
type: string
|
||||
example: ''
|
||||
updatedAt:
|
||||
type: string
|
||||
example: ''
|
||||
createdAt:
|
||||
type: string
|
||||
example: ''
|
||||
ProjectKey:
|
||||
type: object
|
||||
properties:
|
||||
encryptedkey:
|
||||
type: string
|
||||
example: ''
|
||||
nonce:
|
||||
type: string
|
||||
example: ''
|
||||
sender:
|
||||
type: object
|
||||
properties:
|
||||
publicKey:
|
||||
type: string
|
||||
example: ''
|
||||
receiver:
|
||||
type: string
|
||||
example: ''
|
||||
workspace:
|
||||
type: string
|
||||
example: ''
|
||||
CreateSecret:
|
||||
type: object
|
||||
properties:
|
||||
type:
|
||||
type: string
|
||||
example: object
|
||||
properties:
|
||||
type: object
|
||||
properties:
|
||||
test:
|
||||
type: object
|
||||
properties:
|
||||
type:
|
||||
type: string
|
||||
example: integer
|
||||
description:
|
||||
type: string
|
||||
example: '123'
|
||||
example: shared
|
||||
secretKeyCiphertext:
|
||||
type: string
|
||||
example: ''
|
||||
secretKeyIV:
|
||||
type: string
|
||||
example: ''
|
||||
secretKeyTag:
|
||||
type: string
|
||||
example: ''
|
||||
secretValueCiphertext:
|
||||
type: string
|
||||
example: ''
|
||||
secretValueIV:
|
||||
type: string
|
||||
example: ''
|
||||
secretValueTag:
|
||||
type: string
|
||||
example: ''
|
||||
secretCommentCiphertext:
|
||||
type: string
|
||||
example: ''
|
||||
secretCommentIV:
|
||||
type: string
|
||||
example: ''
|
||||
secretCommentTag:
|
||||
type: string
|
||||
example: ''
|
||||
UpdateSecret:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
example: ''
|
||||
secretKeyCiphertext:
|
||||
type: string
|
||||
example: ''
|
||||
secretKeyIV:
|
||||
type: string
|
||||
example: ''
|
||||
secretKeyTag:
|
||||
type: string
|
||||
example: ''
|
||||
secretValueCiphertext:
|
||||
type: string
|
||||
example: ''
|
||||
secretValueIV:
|
||||
type: string
|
||||
example: ''
|
||||
secretValueTag:
|
||||
type: string
|
||||
example: ''
|
||||
secretCommentCiphertext:
|
||||
type: string
|
||||
example: ''
|
||||
secretCommentIV:
|
||||
type: string
|
||||
example: ''
|
||||
secretCommentTag:
|
||||
type: string
|
||||
example: ''
|
||||
Secret:
|
||||
type: object
|
||||
properties:
|
||||
_id:
|
||||
type: string
|
||||
example: ''
|
||||
version:
|
||||
type: number
|
||||
example: 1
|
||||
workspace:
|
||||
type: string
|
||||
example: ''
|
||||
type:
|
||||
type: string
|
||||
example: shared
|
||||
user: {}
|
||||
secretKeyCiphertext:
|
||||
type: string
|
||||
example: ''
|
||||
secretKeyIV:
|
||||
type: string
|
||||
example: ''
|
||||
secretKeyTag:
|
||||
type: string
|
||||
example: ''
|
||||
secretValueCiphertext:
|
||||
type: string
|
||||
example: ''
|
||||
secretValueIV:
|
||||
type: string
|
||||
example: ''
|
||||
secretValueTag:
|
||||
type: string
|
||||
example: ''
|
||||
secretCommentCiphertext:
|
||||
type: string
|
||||
example: ''
|
||||
secretCommentIV:
|
||||
type: string
|
||||
example: ''
|
||||
secretCommentTag:
|
||||
type: string
|
||||
example: ''
|
||||
updatedAt:
|
||||
type: string
|
||||
example: ''
|
||||
createdAt:
|
||||
type: string
|
||||
example: ''
|
||||
securitySchemes:
|
||||
bearerAuth:
|
||||
type: http
|
||||
scheme: bearer
|
||||
bearerFormat: JWT
|
||||
description: >-
|
||||
This security definition uses the HTTP 'bearer' scheme, which allows the
|
||||
client to authenticate using a JSON Web Token (JWT) that is passed in
|
||||
the Authorization header of the request.
|
||||
apiKeyAuth:
|
||||
type: apiKey
|
||||
in: header
|
||||
name: X-API-Key
|
||||
description: >-
|
||||
This security definition uses an API key, which is passed in the header
|
||||
of the request as the value of the "X-API-Key" header. The client must
|
||||
provide a valid key in order to access the API.
|
||||
|
||||
Reference in New Issue
Block a user