> ## Documentation Index
> Fetch the complete documentation index at: https://www.nexrender.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Secrets Management

> Store and manage secure environment variables for rendering jobs. Secrets allow you to reference API keys, storage credentials, or any sensitive values without exposing them in job payloads.

## What Are Secrets?

Secrets are securely stored values that can be referenced in job payloads or upload configurations.\
They are encrypted, team-scoped, and never exposed in plaintext once created.

Use secrets to keep API keys, S3 credentials, or other sensitive environment variables out of job definitions.

## Endpoints

### List Secrets

<CodeGroup>
  ```bash List Secrets theme={null}
  curl -X GET https://api.nexrender.com/api/v2/secrets \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```bash Response theme={null}
  [
    {
      "id": "01K0ABCDEFXYZ1234567GHJ89Q",
      "name": "AWS_ACCESS_KEY_ID",
      "createdAt": "2025-09-09T10:15:32.000Z"
    },
    {
      "id": "01K0ABCDEFXYZ1234567GHJ89R",
      "name": "AWS_SECRET_ACCESS_KEY",
      "createdAt": "2025-09-09T10:16:05.000Z"
    }
  ]
  ```
</CodeGroup>

### Create a Secret

<CodeGroup>
  ```bash Create a Secret theme={null}
  curl -X PUT https://api.nexrender.com/api/v2/secrets \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "AWS_ACCESS_KEY_ID",
      "value": "AKIAIOSFODNN7EXAMPLE"
    }'
  ```

  ```bash Response theme={null}
  {
    "id": "01K0ABCDEFXYZ1234567GHJ89Q",
    "name": "AWS_ACCESS_KEY_ID",
    "createdAt": "2025-09-09T10:15:32.000Z"
  }
  ```
</CodeGroup>

If a secret with the same name exists, that would result into error:

```bash Secret Already Exists theme={null}
{
    "error": "Secret already exists",
    "errorCode": "SECRET_ALREADY_EXISTS"
}
```

### Using Secrets in Rendering Jobs

When defining upload configuration or other sensitive fields inside a job payload, you can reference secrets by instead of hardcoding credentials:

<CodeGroup>
  ```bash Upload Setting In Rendering Job theme={null}
  {
    "upload": {
      "provider": "s3",
      "params": {
        "region": "us-east-1",
        "bucket": "my-renders",
        "accessKeyId": "${secrets.AWS_ACCESS_KEY_ID}",
        "accessKeySecret": "${secrets.AWS_SECRET_ACCESS_KEY}"
      }
    }
  } 
  ```
</CodeGroup>

This way, Nexrender Cloud will resolve secrets at runtime without ever exposing their values in logs or responses.

Secrets can be used in `upload` object, `assets`, and in `webhook` fields.

## Removing Secrets

<CodeGroup>
  ```bash Remove Secret by ID theme={null}
    curl --request DELETE \
    --url https://api.nexrender.com/api/v2/secrets/<SECRET_ID> \
    --header "Authorization: Bearer <YOUR_API_TOKEN>"
  ```
</CodeGroup>

The endpoint returns **200 OK** on success and typically no response body.

## Best Practices

* Use secrets for all credentials (API keys, S3 credentials, webhooks with auth).
* Prefer fine-grained secrets (per-project, per-environment) rather than global catch-alls.


## OpenAPI

````yaml PUT /secrets
openapi: 3.0.4
info:
  title: Nexrender API
  version: '2.0'
  description: >
    REST API for the Nexrender cloud rendering platform, enabling programmatic
    control over After Effects template processing, job management, and asset
    handling.


    Features include:


    - Template upload and management (AEP, MOGRT, ZIP files)

    - Job creation and status monitoring with real-time progress

    - Job nesting for multi-composition renders (parent/child jobs)

    - Job stitching to combine multiple videos into one

    - Batch job creation for submitting up to 1000 jobs at once

    - Font library management for typography consistency

    - Secret management for secure API key storage

    - Webhook notifications for job lifecycle events

    - Asset injection for dynamic content replacement


    Authentication is required for all endpoints using Bearer token
    authorization.
servers:
  - url: https://api.nexrender.com/api/v2
    description: Production API server
security:
  - apiToken: []
paths:
  /secrets:
    put:
      tags:
        - Secret Management
      summary: Create a new secret
      description: Create a new secret. Secret values are encrypted and stored securely.
      operationId: createOrUpdateSecret
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SecretCreation'
      responses:
        '201':
          description: Secret successfully created
        '400':
          description: Invalid request - missing required fields or invalid secret data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '401':
          description: Unauthorized - invalid or missing API token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict - secret with this name already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    SecretCreation:
      type: object
      description: Configuration for creating a secret
      properties:
        name:
          type: string
          description: Secret name/key for identification and reference
        value:
          type: string
          description: Secret value to store securely (will be encrypted)
      required:
        - name
        - value
    ValidationErrorResponse:
      type: object
      description: Validation error response with detailed field information
      properties:
        error:
          type: string
          description: Main error message
        details:
          type: array
          description: Array of specific validation errors for individual fields
          items:
            type: object
            properties:
              field:
                type: string
                description: Field name that failed validation
              message:
                type: string
                description: Specific validation error for this field
    ErrorResponse:
      type: object
      description: Standard error response format
      properties:
        error:
          type: string
          description: Human-readable error message explaining what went wrong
      required:
        - error
  securitySchemes:
    apiToken:
      type: http
      scheme: bearer
      description: >
        Bearer token authentication using API tokens for team-based access
        control.


        You can generate your own API token at:
        https://app.nexrender.com/settings/api-tokens

````