openapi: 3.2.0 info: title: Certificate Manager - SaaS Service Accounts API version: '1.0' servers: - description: US Region url: https://api.venafi.cloud - description: EU Region url: https://api.eu.venafi.cloud - description: AU Region url: https://api.au.venafi.cloud - description: UK Region url: https://api.uk.venafi.cloud - description: SG Region url: https://api.sg.venafi.cloud - description: CA Region url: https://api.ca.venafi.cloud tags: - name: Service Accounts paths: /v1/serviceaccounts: get: operationId: get-v1-serviceaccounts responses: '200': content: application/json: schema: $ref: '#/components/schemas/GetServiceAccountsResponseBody' description: The list of all Service Account details the user has access to '400': description: BadRequest '401': description: Unauthorized '500': description: InternalServerError security: - tppl-api-key: [] summary: Retrieves all the Service Accounts the user has access to tags: - Service Accounts post: description: Creates a Service Account with the information provided. The service account is later used for machine to machine authentication. For rsaKey authentication service accounts publicKey key is required. Provide authenticationType field for creating other service accounts with another type of authentication. operationId: create-v1-serviceaccounts requestBody: content: application/json: examples: Custom API Integration: $ref: '#/components/examples/CreateCustomAPIReqBodyExample' Firefly SA: $ref: '#/components/examples/CreateFireflyReqBodyExample' Firefly SA (Auto-generate credentials): $ref: '#/components/examples/CreateFireflyAutogenerateReqBodyExample' schema: $ref: '#/components/schemas/CreateServiceAccountRequestBody' description: The Service Account data required: true responses: '200': content: application/json: examples: Firefly SA: $ref: '#/components/examples/CreateFireflyResBodyExample' Firefly SA (Auto-generate credentials): $ref: '#/components/examples/CreateFireflyAutogenerateResBodyExample' schema: $ref: '#/components/schemas/CreateServiceAccountResponseBody' description: The id assigned to the created Service Account. If the Service Account has CyberArk registry purpose and is created with ociToken authentication type, the ociRegistryToken and ociAccountName are returned in the response. '400': description: BadRequest. Return ErrInvalidPayload when creating rsaKey authentication service accounts and publicKey not provided. '401': description: Unauthorized '500': description: InternalServerError security: - tppl-api-key: [] summary: Creates a Service Account tags: - Service Accounts /v1/serviceaccounts/{id}: get: description: Retrieves the information of an Service Account associated to the given id operationId: get-v1-serviceaccounts-byId parameters: - description: The ID corresponding to the Service Account you want to retrieve in: path name: id required: true schema: example: 933507dd-0286-11ef-bc25-8a00a468403f format: UUID type: string x-go-type: uuid.UUID x-go-type-import: path: github.com/google/uuid responses: '200': content: application/json: examples: Get Service Account by ID: $ref: '#/components/examples/GetServiceAccountsByClientIDResBodyExample' schema: $ref: '#/components/schemas/ServiceAccountDetails' description: The Service Account details for the given id '400': description: BadRequest '401': description: Unauthorized '500': description: InternalServerError security: - tppl-api-key: [] summary: Gets a Service Account tags: - Service Accounts patch: description: Updates the specified fields for a given service account matching the provided id. Providing either a new credentialLifetime or a new publicKey will result of the corresponding credentials associated to this Service Account operationId: patch-v1-serviceaccounts-byId parameters: - description: The ID corresponding to the Service Account you want to update in: path name: id required: true schema: example: 933507dd-0286-11ef-bc25-8a00a468403f format: UUID type: string x-go-type: uuid.UUID x-go-type-import: path: github.com/google/uuid requestBody: content: application/json: schema: $ref: '#/components/schemas/PatchServiceAccountByClientIDRequestBody' description: The data to update required: true responses: '204': description: The Service Account was updated successfully '400': description: BadRequest '401': description: Unauthorized '500': description: InternalServerError security: - tppl-api-key: [] summary: Updates a Service Account tags: - Service Accounts delete: description: Deletes the Service Account corresponding to the provided id. Deleting a Service Account also invalidates its associated credentials. operationId: delete-v1-serviceaccounts-byId parameters: - description: The ID corresponding to the Service Account you want to delete in: path name: id required: true schema: example: 933507dd-0286-11ef-bc25-8a00a468403f format: UUID type: string x-go-type: uuid.UUID x-go-type-import: path: github.com/google/uuid responses: '204': description: The Service Account was deleted successfully '400': description: BadRequest '401': description: Unauthorized '500': description: InternalServerError security: - tppl-api-key: [] summary: Deletes a Service Account tags: - Service Accounts /v1/serviceaccounts/scopes: get: operationId: get-v1-serviceaccountscopes responses: '200': content: application/json: schema: $ref: '#/components/schemas/GetServiceAccountScopesResponseBody' description: The list of all Service Account Scopes available for the user '400': description: BadRequest '401': description: Unauthorized '500': description: InternalServerError security: - tppl-api-key: [] summary: Retrieves all the Service Accounts Scopes available for the user tags: - Service Accounts /v1/serviceaccounts/{id}/ocitoken: put: description: Regenerate the OCI registry token for a given service account matching the provided id. Providing a new OCI registry token to this Service Account and sending it back to the client back. Calling this endpoint will remove the current token for the service account and create a new one. Old token can not be used. operationId: put-v1-serviceaccounts-byId-ocitoken parameters: - description: The ID corresponding to the Service Account you want to regenerate the OCI registry token in: path name: id required: true schema: example: 933507dd-0286-11ef-bc25-8a00a468403f format: UUID type: string x-go-type: uuid.UUID x-go-type-import: path: github.com/google/uuid responses: '200': content: application/json: schema: $ref: '#/components/schemas/PutServiceAccountByClientIDOCITokenResponseBody' description: The Service Account OCI registry token has been regenerated '400': description: BadRequest. This also happens when trying to regenerate token for account without token based authentication '401': description: Unauthorized '500': description: InternalServerError security: - tppl-api-key: [] summary: Regenerate the OCI registry token for a Service Account with registry scope tags: - Service Accounts /v1/serviceaccounts/{id}/credentials: put: description: Updates the specified credentials for a given service account matching the provided id. Providing either a new credentialLifetime or a new publicKey will result of the corresponding credentials associated to this Service Account operationId: put-v1-serviceaccounts-byId-credentials parameters: - description: The ID corresponding to the Service Account you want to update in: path name: id required: true schema: example: 933507dd-0286-11ef-bc25-8a00a468403f format: UUID type: string x-go-type: uuid.UUID x-go-type-import: path: github.com/google/uuid requestBody: content: application/json: schema: $ref: '#/components/schemas/PutServiceAccountByClientIDCredentialsRequestBody' description: The data to update required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/PutServiceAccountByClientIDCredentialsResponseBody' description: The Service Account Credentials were updated successfully '400': description: BadRequest '401': description: Unauthorized '500': description: InternalServerError security: - tppl-api-key: [] summary: Updates a Service Account credentials tags: - Service Accounts components: schemas: ServiceAccountDetailsNoKey: allOf: - $ref: '#/components/schemas/ServiceAccountBaseObjectNoKey' - $ref: '#/components/schemas/Details' example: authenticationType: rsaKey companyId: 145f12e0-fdbf-11ee-b275-2754a4f7e272 credentialLifetime: 365 credentialsExpiringOn: '2025-01-01T00:00:00.000000Z' enabled: true id: 933507dd-0286-11ef-bc25-8a00a468403f name: Service Account I owner: 2620f8e0-fdbf-11ee-b275-2754a4f7e272 scopes: - distributed-issuance updatedBy: 150760d0-fdbf-11ee-b275-2754a4f7e272 updatedOn: '2024-01-01T00:00:00.000000Z' ServiceAccountBasePatchObjectNoKey: properties: applications: description: The list of applications for which the account is authorized example: - dc96438b-7a80-464b-a09b-9e5ec746c3e3 - 5bce5ff4-a69b-4e78-9b7e-6d4029995000 items: $ref: '#/components/schemas/Application' type: array uniqueItems: true audience: description: The intended audience or recipients of the entity example: Audience maxLength: 250 minLength: 1 type: string credentialLifetime: description: The number of days for which the credentials will be valid before expiring and requiring renewal maximum: 365 minimum: 1 type: integer issuerURL: description: The URL of the entity issuer, providing the source or origin example: https://accounts.google.com/ maxLength: 250 minLength: 1 type: string jwksURI: description: The URI pointing to the JSON Web Key Set (JWKS) for the entity, facilitating secure authentication example: https://www.googleapis.com/oauth2/v3/certs maxLength: 250 minLength: 1 type: string name: description: User friendly name for the given account maxLength: 250 minLength: 1 type: string owner: description: The UUID of the owning team format: UUID type: string x-go-type: uuid.UUID x-go-type-import: path: github.com/google/uuid scopes: description: The list of scopes for which the account is authorized items: $ref: '#/components/schemas/Scope' minItems: 1 type: array uniqueItems: true subject: description: The subject of the entity, representing the main topic or title. example: Subject maxLength: 250 minLength: 1 type: string type: object PutServiceAccountByClientIDCredentialsResponseBody: properties: credentialExpiresIn: description: Expiration in hours for service account credentials format: float type: number x-go-type: float64 type: object ServiceAccountBaseObjectNoKey: properties: applications: description: The list of applications for which the account is authorized example: - dc96438b-7a80-464b-a09b-9e5ec746c3e3 - 5bce5ff4-a69b-4e78-9b7e-6d4029995000 items: $ref: '#/components/schemas/Application' type: array uniqueItems: true audience: description: The intended audience or recipients of the entity example: Audience maxLength: 250 minLength: 1 type: string authenticationType: description: Type of authentication used in the scope. Currently supporting two types rsaKey and ociToken example: rsaKey type: string companyId: description: The UUID of the company/tenant format: UUID type: string x-go-type: uuid.UUID x-go-type-import: path: github.com/google/uuid credentialLifetime: description: The number of days for which the credentials will be valid before expiring and requiring renewal example: 365 maximum: 365 minimum: 1 type: integer issuerURL: description: The URL of the entity issuer, providing the source or origin example: https://accounts.google.com/ maxLength: 250 minLength: 1 type: string jwksURI: description: The URI pointing to the JSON Web Key Set (JWKS) for the entity, facilitating secure authentication example: https://www.googleapis.com/oauth2/v3/certs maxLength: 250 minLength: 1 type: string name: description: User friendly name for the given account maxLength: 250 minLength: 1 type: string owner: description: The UUID of the owning team format: UUID type: string x-go-type: uuid.UUID x-go-type-import: path: github.com/google/uuid scopes: description: The list of scopes for which the account is authorized example: - distributed-issuance items: $ref: '#/components/schemas/Scope' minItems: 1 type: array uniqueItems: true subject: description: The subject of the entity, representing the main topic or title. example: Subject maxLength: 250 minLength: 1 type: string type: object ScopeDetails: description: The service account authorization scopes detailed example: authenticationType: rsaKey id: distributed-issuance readableName: Distributed Issuance properties: authenticationType: description: Type of authentication used in the scope type: string id: description: ID for the given scope type: string readableName: description: User friendly name for the scope type: string required: - id - readableName type: object Application: description: Application ID to associate with the service account format: UUID type: string x-go-type: uuid.UUID x-go-type-import: path: github.com/google/uuid ServiceAccountDetails: allOf: - $ref: '#/components/schemas/ServiceAccountBaseObject' - $ref: '#/components/schemas/Details' CreateServiceAccountRequestBody: allOf: - $ref: '#/components/schemas/ServiceAccountBaseObject' - required: - name - scopes type: object example: applications: - dc96438b-7a80-464b-a09b-9e5ec746c3e3 - 5bce5ff4-a69b-4e78-9b7e-6d4029995000 authenticationType: rsaKey credentialLifetime: 30 name: Firefly SA owner: 2620f8e0-fdbf-11ee-b275-2754a4f7e272 publicKey: '-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAzRCyRWzXlyhFp3RcUrum1Q6j7YR8jyL0L1fWnh7zgt4=\n-----END PUBLIC KEY-----' scopes: - distributed-issuance ServiceAccountPatchBaseObject: allOf: - $ref: '#/components/schemas/ServiceAccountBasePatchObjectNoKey' - properties: publicKey: description: The client generated public key maxLength: 2000 type: string type: object PutServiceAccountByClientIDOCITokenResponseBody: properties: ociRegistryToken: description: The OCI registry token generated for a robot in case of the registry scope type: string type: object CreateServiceAccountResponseBody: example: id: 933507dd-0286-11ef-bc25-8a00a468403f privateKey: 'REDACTED_PRIVATE_KEY_EXAMPLE ' publicKey: '-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAzRCyRWzXlyhFp3RcUrum1Q6j7YR8jyL0L1fWnh7zgt4=\n-----END PUBLIC KEY-----' properties: id: description: The ID for this service account format: UUID type: string x-go-type: uuid.UUID x-go-type-import: path: github.com/google/uuid ociAccountName: description: The OCI account name generated for a robot in case of the registry scope type: string ociRegistryToken: description: The OCI registry token generated for a robot in case of the registry scope type: string privateKey: description: The generated private key for the service account when not providing a public key on the create payload type: string publicKey: description: The generated public key for the service account when not providing a public key on the create payload type: string type: object PatchServiceAccountByClientIDRequestBody: allOf: - $ref: '#/components/schemas/ServiceAccountPatchBaseObject' - properties: enabled: description: Indicates if the given service account must be enabled or disabled where disable means that the credentials cannot be used for authentication type: boolean type: object example: credentialLifetime: 365 enabled: true name: New name owner: 2620f8e0-fdbf-11ee-b275-2754a4f7e272 publicKey: '-----BEGIN PUBLIC KEY----- MCowBQYDK2VwAyEAor3JRni8bObnKbmWzRubiNyKMoCXLVrswqiMm2h8zl8= -----END PUBLIC KEY----- ' scopes: - distributed-issuance Scope: description: The service account authorization scopes example: distributed-issuance type: string PutServiceAccountByClientIDCredentialsRequestBody: example: extendCredentialLifetime: true properties: extendCredentialLifetime: description: Extend the credential lifetime type: boolean required: - extendCredentialLifetime type: object GetServiceAccountsResponseBody: example: - authenticationType: rsaKey companyId: 145f12e0-fdbf-11ee-b275-2754a4f7e272 credentialLifetime: 365 credentialsExpiringOn: '2025-01-01T00:00:00.000000Z' enabled: true id: 933507dd-0286-11ef-bc25-8a00a468403f name: Service Account I owner: 2620f8e0-fdbf-11ee-b275-2754a4f7e272 scopes: - distributed-issuance updatedBy: 150760d0-fdbf-11ee-b275-2754a4f7e272 updatedOn: '2024-01-01T00:00:00.000000Z' - authenticationType: rsaKey companyId: 145f12e0-fdbf-11ee-b275-2754a4f7e272 credentialLifetime: 365 credentialsExpiringOn: '2025-01-01T00:00:00.000000Z' enabled: true id: 933507dd-0286-11ef-bc25-8a00a468403a name: Service Account II owner: 2620f8e0-fdbf-11ee-b275-2754a4f7e272 scopes: - distributed-issuance updatedBy: 150760d0-fdbf-11ee-b275-2754a4f7e272 updatedOn: '2024-01-01T00:00:00.000000Z' items: $ref: '#/components/schemas/ServiceAccountDetailsNoKey' type: array GetServiceAccountScopesResponseBody: example: - authenticationType: rsaKey id: distributed-issuance readableName: Distributed Issuance items: $ref: '#/components/schemas/ScopeDetails' type: array Details: properties: credentialsExpiringOn: description: The exact date on which the credentials will expire format: date-time type: string enabled: description: Indicates if the given service account must be enabled or disabled where disable means that the credentials cannot be used for type: boolean id: description: The ID for this service account format: UUID type: string x-go-type: uuid.UUID x-go-type-import: path: github.com/google/uuid lastUsedOn: description: The last time the account credentials were used to authenticate a machine format: date-time type: string updatedBy: description: The UUID of the latest user that modified the account format: UUID type: string x-go-type: uuid.UUID x-go-type-import: path: github.com/google/uuid updatedOn: description: The last time the account details were updated format: date-time type: string type: object ServiceAccountBaseObject: allOf: - $ref: '#/components/schemas/ServiceAccountBaseObjectNoKey' - properties: publicKey: description: The client generated public key maxLength: 2000 type: string type: object examples: CreateFireflyResBodyExample: value: id: 933507dd-0286-11ef-bc25-8a00a468403f publicKey: '-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAzRCyRWzXlyhFp3RcUrum1Q6j7YR8jyL0L1fWnh7zgt4=\n-----END PUBLIC KEY-----' CreateFireflyReqBodyExample: description: In this example, it allows you to create Service Accounts using the Auto-generate mode to create a keypair and download the private key. value: authenticationType: rsaKey credentialLifetime: 30 name: Firefly SA owner: 2620f8e0-fdbf-11ee-b275-2754a4f7e272 publicKey: '-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAzRCyRWzXlyhFp3RcUrum1Q6j7YR8jyL0L1fWnh7zgt4=\n-----END PUBLIC KEY-----' scopes: - distributed-issuance GetServiceAccountsByClientIDResBodyExample: value: authenticationType: rsaKey companyId: 145f12e0-fdbf-11ee-b275-2754a4f7e272 credentialLifetime: 365 credentialsExpiringOn: '2025-01-01T00:00:00.000000Z' enabled: true id: 933507dd-0286-11ef-bc25-8a00a468403f name: Test owner: 2620f8e0-fdbf-11ee-b275-2754a4f7e272 publicKey: '-----BEGIN PUBLIC KEY----- MCowBQYDK2VwAyEAor3JRni8bObnKbmWzRubiNyKMoCXLVrswqiMm2h8zl8= -----END PUBLIC KEY----- ' scopes: - distributed-issuance updatedBy: 150760d0-fdbf-11ee-b275-2754a4f7e272 updatedOn: '2024-01-01T00:00:09.000000Z' CreateFireflyAutogenerateResBodyExample: value: id: 933507dd-0286-11ef-bc25-8a00a468403f privateKey: 'REDACTED_PRIVATE_KEY_EXAMPLE ' publicKey: '-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAzRCyRWzXlyhFp3RcUrum1Q6j7YR8jyL0L1fWnh7zgt4=\n-----END PUBLIC KEY-----' CreateFireflyAutogenerateReqBodyExample: description: In this example, it allows you to create Service Accounts using the Auto-generate mode to create a keypair and download the private key. value: authenticationType: rsaKey credentialLifetime: 30 name: Firefly SA owner: 2620f8e0-fdbf-11ee-b275-2754a4f7e272 publicKey: '' scopes: - distributed-issuance CreateCustomAPIReqBodyExample: value: applications: - dc96438b-7a80-464b-a09b-9e5ec746c3e3 - 5bce5ff4-a69b-4e78-9b7e-6d4029995000 audience: Audience authenticationType: rsaKeyFederated issuerURL: https://accounts.google.com/ jwksURI: https://www.googleapis.com/oauth2/v3/certs name: Firefly SA owner: 2620f8e0-fdbf-11ee-b275-2754a4f7e272 scopes: - distributed-issuance subject: Subject securitySchemes: service-account: in: header name: service-account type: apiKey tppl-api-key: in: header name: tppl-api-key type: apiKey x-readme: samples-languages: - curl - go - java - javascript - node - python