openapi.yml

openapi: "3.0.0"

info:
  description: "This is an API definition for CyberArk Conjur Open Source. You can find out more at [Conjur.org](https://www.conjur.org/)."
  version: 5.3.1
  title: "Conjur"
  contact:
    email: "conj_maintainers@cyberark.com"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"

servers: 
- url: /

tags:
- name: "authentication"
  description: "Authentication"
- name: "secrets"
  description: "Secrets"
- name: "policies"
  description: "Policies"
- name: "roles"
  description: "RBAC"
- name: "host factory"
  description: "Host factories"
- name: "public keys"
  description: "SSH keys"
- name: "resources"
  description: "Resources"
- name: "status"
  description: "Server status"
- name: "certificate authority"
  description: "Certificate authority"

components:
  schemas:
    AccountName:
      description: "Conjur account name"
      type: string
      minLength: 1
      example: "default"

    Count:
      description: "Return only the count of results"
      type: boolean
      example: true

    Kind:
      type: string
      minLength: 1
      example: "variable"

    Limit:
      description: "Return no more than this number of results"
      type: integer
      example: 10

    Offset:
      description: "Skips this many items before returning the rest"
      type: integer
      example: 20

    ResourceID:
      type: string
      minLength: 1
      example: "prod%2Faws%2Fdb-password"
      description: |
        Resource identifier. Requires to be encoded when in path.

        ##### Examples:

        - `myapp-01` -> `myapp-01` (unchanged)
        - `alice@devops` -> `alice%40devops`
        - `prod/aws/db-password` -> `prod%2Faws%2Fdb-password`
        - `research+development` -> `research%2Bdevelopment`
        - `sales&marketing` -> `sales%26marketing`

    ResourceVersion:
      description: "Version of the resource (Conjur keeps the last 20 versions of a secret)"
      type: integer
      example: 1

    RoleType:
      type: string
      minLength: 1
      description: |
        ##### Kinds of roles:

        - User: one unique wonderful human
        - Host: a single logical machine (in the broad sense, not just physical)
        - Layer: a collection of hosts that have the same privileges
        - Group: a collection of users and groups that have the same privileges
        - Policy: a role which owns of a set of related object

        Any identifier included in the URL must be URL-encoded to be recognized by the Conjur API.

        ##### Resource Identifiers:

        - `myapp-01` -> `myapp-01` (unchanged)
        - `alice@devops` -> `alice%40devops`
        - `prod/aws/db-password` -> `prod%2Faws%2Fdb-password`
        - `research+development` -> `research%2Bdevelopment`
        - `sales&marketing` -> `sales%26marketing`

  parameters:
    ServiceID:
      name: service_id
      in: path
      required: true
      description: "URL-Encoded authenticator service ID"
      example: prod%2fgke
      schema:
        type: string

    RequestID:
      name: X-Request-Id
      in: header
      required: false
      description: |
        Add an ID to the request being made so it can be tracked in Conjur.
        If not provided the server will automatically generate one.
      example: "test-id"
      schema:
        type: string
        pattern: '^[a-zA-Z\d-]{1,255}$'

  responses:
    BadRequest:
      description: "The server cannot process the request due to malformed request syntax"
    Busy:
      description: "Similar operation already in progress, retry after a delay"
    InadequatePrivileges:
      description: "The authenticated user lacks the necessary privileges"
    InternalServerError:
      description: "Malfromed request, rejected by the server"
    ResourceNotFound:
      description: "The requested resource does not exist, the authenticated user lacks the required privileges to enumerate this resource, or its value has not been set"
    ResourcesNotFound:
      description: "At least one resource was unable to be found"
    UnauthorizedError:
      description: "Authentication information is missing or invalid"
    UnprocessableEntity:
      description: "A request parameter was either missing or invalid."

  securitySchemes:
    basicAuth:
      description: |
        Basic authentication with Conjur username and password (users only)
        or API key (hosts and users).
      type: http
      scheme: basic
    conjurAuth:
      description: "Conjur access token in `Token token=<base64_encoded_token>` format."
      type: apiKey
      in: header
      name: Authorization
    conjurKubernetesMutualTls:
      description: |
        Conjur Kubernetes authenticator mutual TLS authentication.
        To authenticate using this method, you must provide a trusted client
        certificate
      type: http
      scheme: mutual


security:
  - basicAuth: []
  - conjurAuth: []
  - conjurKubernetesMutualTls: []

paths:

# ========== AUTHENTICATION ===========

  '/authn/{account}/login':
    $ref: 'authentication.yml#/components/paths/DefaultLogin'

  '/authn-k8s/{service_id}/inject_client_cert':
    $ref: 'authentication.yml#/components/paths/K8sInjectClientCert'

  '/authn-ldap/{service_id}/{account}/login':
    $ref: 'authentication.yml#/components/paths/LDAPLogin'

  '/authn/{account}/{login}/authenticate':
    $ref: 'authentication.yml#/components/paths/DefaultAuthenticate'

  '/authn-iam/{service_id}/{account}/{login}/authenticate':
    $ref: 'authentication.yml#/components/paths/AWSAuthenticate'

  '/authn-azure/{service_id}/{account}/{login}/authenticate':
    $ref: 'authentication.yml#/components/paths/AzureAuthenticate'

  '/authn-gcp/{account}/authenticate':
    $ref: 'authentication.yml#/components/paths/GCPAuthenticate'

  '/authn-k8s/{service_id}/{account}/{login}/authenticate':
    $ref: 'authentication.yml#/components/paths/KubernetesAuthenticate'

  '/authn-ldap/{service_id}/{account}/{login}/authenticate':
    $ref: 'authentication.yml#/components/paths/LDAPAuthenticate'

  '/authn-oidc/{service_id}/{account}/authenticate':
    $ref: 'authentication.yml#/components/paths/OIDCAuthenticate'

  '/authn-jwt/{service_id}/{account}/authenticate':
    $ref: 'authentication.yml#/components/paths/JWTAuthenticate'

  '/authn-jwt/{service_id}/{account}/{id}/authenticate':
    $ref: 'authentication.yml#/components/paths/JWTAuthenticateWithId'

  '/authn/{account}/password':
    $ref: 'authentication.yml#/components/paths/ChangePassword'

  '/authn/{account}/api_key':
    $ref: 'authentication.yml#/components/paths/RotateApiKey'

  '/{authenticator}/{account}':
    $ref: 'authentication.yml#/components/paths/EnableAuthenticator'

  '/{authenticator}/{service_id}/{account}':
    $ref: 'authentication.yml#/components/paths/EnableAuthenticatorInstance'

# ========== STATUS ===========

  '/whoami':
    $ref: 'status.yml#/components/paths/WhoAmI'

  '/{authenticator}/{service_id}/{account}/status':
    $ref: 'status.yml#/components/paths/ServiceAuthenticatorStatus'

  '/authn-gcp/{account}/status':
    $ref: 'status.yml#/components/paths/AuthenticatorStatus'

  '/authenticators':
    $ref: 'status.yml#/components/paths/AuthenticatorsIndex'

  '/health':
    x-conjur-settings:
      enterprise-only: true
    $ref: 'status.yml#/components/paths/Health'

  '/remote_health/{remote}':
    x-conjur-settings:
      enterprise-only: true
    $ref: 'status.yml#/components/paths/RemoteHealth'

  '/info':
    x-conjur-settings:
      enterprise-only: true
    $ref: 'status.yml#/components/paths/Info'

# ========== SECRETS ==================

  '/secrets/{account}/{kind}/{identifier}':
    $ref: 'secrets.yml#/components/paths/Secret'

  '/secrets':
    $ref: 'secrets.yml#/components/paths/BatchSecrets'

# ========== POLICIES =================

  '/policies/{account}/policy/{identifier}':
    $ref: 'policies.yml#/components/paths/Policies'

# ========== ROLES ====================

  '/roles/{account}/{kind}/{identifier}':
    $ref: 'roles.yml#/components/paths/Roles'

# ========== RESOURCES ================

  '/resources':
    $ref: 'resources.yml#/components/paths/ListResources'

  '/resources/{account}':
    $ref: 'resources.yml#/components/paths/ListResourcesOnAccount'

  '/resources/{account}/{kind}':
    $ref: 'resources.yml#/components/paths/ListSimilarResourcesOnAccount'

  '/resources/{account}/{kind}/{identifier}':
    $ref: 'resources.yml#/components/paths/SingleResource'

# ========== HOST FACTORY =============

  '/host_factory_tokens':
    $ref: 'host-factory.yml#/components/paths/CreateHostToken'

  '/host_factory_tokens/{token}':
    $ref: 'host-factory.yml#/components/paths/RevokeHostToken'

  '/host_factories/hosts':
    $ref: 'host-factory.yml#/components/paths/CreateHost'

# ========== PUBLIC KEYS ==============

  '/public_keys/{account}/{kind}/{identifier}':
    $ref: 'public-keys.yml#/components/paths/PublicKeys'

# ========== CERTIFICATE AUTHORITY ====

  '/ca/{account}/{service_id}/sign':
    $ref: 'cert-auth.yml#/components/paths/Sign'

# TODO: Seed Service

externalDocs:
  description: "Find out more about Conjur"
  url: "https://conjur.org"