Create an API key

OpenAPI contract

Method

POST

Path

/api/v1/api-keys

Security

jwtBearer (bearer)

Response status

201 400 401 403 404 409 429 500

Request and response schemas

JSON

{
  "requestBody": {
    "application/json": {
      "$ref": "#/components/schemas/CreateApiKeyRequest"
    }
  },
  "responses": {
    "201": {
      "description": "API key created",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/CreateApiKeyResponse"
        }
      }
    },
    "400": {
      "description": "Invalid request",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/RequestError"
        }
      }
    },
    "401": {
      "description": "Authentication required or invalid",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/SecurityError"
        }
      }
    },
    "403": {
      "description": "Authenticated but not permitted",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/SecurityError"
        }
      }
    },
    "404": {
      "description": "Requested API key was not found",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    },
    "409": {
      "description": "Active API-key limit reached",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    },
    "429": {
      "description": "Rate limit exceeded",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/SecurityError"
        }
      }
    },
    "500": {
      "description": "Unexpected server error",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  }
}

POST /api/v1/api-keys is JWT-only. Send name (nonblank, at most 100 characters), a nonempty scopes set, and optional future expiresAt. You may also set usageLimitNcu, an NCU ceiling for each account credit-refresh period, and allowedCidrs, up to 50 strict IPv4/IPv6 literals or CIDR networks. Empty CIDRs mean unrestricted use.

Supported scopes are build:read, build:write, artifact:read, project:read, project:write, processor:read, processor:write, and analytics:read. Each scope is independent: write does not imply read. The successful response contains API-key metadata and the one-time secret.

Copy the returned nfy_ secret directly into a secure CI secret store; it is never returned by listing. Metadata exposes only a non-secret nfy_ prefix. Responses are marked Cache-Control: no-store. Keys cannot create, list, update, or revoke keys. Invalid scopes, expiry, usage limits, or IP entries are rejected; the active-key limit produces a conflict.

http

POST /api/v1/api-keys
Authorization: Bearer <access token>
Content-Type: application/json