Certificate Management

Manage certificates for mutual TLS authentication for a tenant. The authentication enhances security by certifying that incoming HTTP notification requests from GTV to your infrastructure are from a trusted GTV application before any data or information is transmitted. The certificate management allows you to use self-service to retrieve, upload, edit, reupload, delete, or change the status of your certificates. Learn more about Certificate Management through the UI guide.

For more information, please search through the Gotransverse online documentation:

Terms of Service: Public use
Request Content-Types: application/json
Response Content-Types: application/json
Version: 2.1.0.2

Authentication

api_key_header

An authorization key that is assigned to perform an action in the system. Passed in the form of a X-Api-Key header that is attached to the call. e.g 325509ed604449279d4587c5e35e3235

type
apiKey
name
X-Api-Key
in
header

Paths

Get certificates

GET /certificates

Uses query keys to retrieve a list of certificates available for this tenant.

page_number: integer x ≥ 1 1
in query

The page number for multiple page queries. Use the page_size query parameter to define the size of pages.

page_size: integer 1 ≤ x ≤ 500 500
in query

The page size for multiple page queries. Default maximum is 500.

name: string
in query

The name of the certificate.

name_starts_with: string
in query

The first few characters of the certificate name.

sort: string name, status, valid_from, valid_to name
in query

The sort field by which to query. It allows API consumers to view response data evaluated against the specified sort criteria. For example, querying by 'name', which is the default, returns a list of certificates sorted by name.

sort_direction: string asc, desc asc
in query

Sorts query results in ascending or descending order. By default, query results are sorted in the ascending order.

Success

401 Unauthorized

Authentication failed.

403 Forbidden

Access denied.

404 Not Found

Entity not found.

422 Unprocessable Entity

Validation failure.

Response Example (200 OK)
[
  {
    "created_on": "string (date-time)",
    "uploaded_on": "string (date-time)",
    "valid_from": "string (date-time)",
    "valid_to": "string (date-time)",
    "name": "string",
    "status": "string",
    "description": "string",
    "certificate_chain": "string",
    "key_algorithm": "string",
    "application_types": [
      "string"
    ],
    "id": "string"
  }
]
Response Headers (200 OK)
X-Total-Count

The total results for the particular query. Used to drive paging requests.

integer (int64)
X-Element-Count

The total count of available entities. Used to drive paging requests.

integer (int64)
X-Total-Pages

The total count of available pages. Used to drive paging requests.

integer (int64)
Response Example (401 Unauthorized)
{
  "code": "string",
  "message": "string"
}
Response Example (403 Forbidden)
{
  "code": "string",
  "message": "string"
}
Response Example (404 Not Found)
{
  "code": "string",
  "message": "string"
}
Response Example (422 Unprocessable Entity)
{
  "code": "string",
  "message": "string"
}

Publish certificate

POST /certificates

Publishes a new certificate to Gotransverse. The request payload must include a unique name of the certificate and Gotransverse application type where the certificate can be applied such as EXTERNAL_APPLICATION.

A payload for publishing a new certificate.

Request Content-Types: application/json
Request Example
{
  "private_key": "string",
  "name": "string",
  "status": "string",
  "description": "string",
  "certificate_chain": "string",
  "key_algorithm": "string",
  "application_types": [
    "string"
  ]
}

Success

401 Unauthorized

Authentication failed.

403 Forbidden

Access denied.

404 Not Found

Entity not found.

422 Unprocessable Entity

Validation failure.

Response Content-Types: application/json
Response Example (200 OK)
{
  "created_on": "string (date-time)",
  "uploaded_on": "string (date-time)",
  "valid_from": "string (date-time)",
  "valid_to": "string (date-time)",
  "name": "string",
  "status": "string",
  "description": "string",
  "certificate_chain": "string",
  "key_algorithm": "string",
  "application_types": [
    "string"
  ],
  "id": "string"
}
Response Example (401 Unauthorized)
{
  "code": "string",
  "message": "string"
}
Response Example (403 Forbidden)
{
  "code": "string",
  "message": "string"
}
Response Example (404 Not Found)
{
  "code": "string",
  "message": "string"
}
Response Example (422 Unprocessable Entity)
{
  "code": "string",
  "message": "string"
}

Get certificate by UUID

GET /certificates/{certificate-id}

Retrieves an existing certificate by the associated UUID.

certificate-id: string
in path

The UUID of the certificate.

Success

401 Unauthorized

Authentication failed.

403 Forbidden

Access denied.

404 Not Found

Entity not found.

422 Unprocessable Entity

Validation failure.

Response Content-Types: application/json
Response Example (200 OK)
{
  "created_on": "string (date-time)",
  "uploaded_on": "string (date-time)",
  "valid_from": "string (date-time)",
  "valid_to": "string (date-time)",
  "name": "string",
  "status": "string",
  "description": "string",
  "certificate_chain": "string",
  "key_algorithm": "string",
  "application_types": [
    "string"
  ],
  "id": "string"
}
Response Example (401 Unauthorized)
{
  "code": "string",
  "message": "string"
}
Response Example (403 Forbidden)
{
  "code": "string",
  "message": "string"
}
Response Example (404 Not Found)
{
  "code": "string",
  "message": "string"
}
Response Example (422 Unprocessable Entity)
{
  "code": "string",
  "message": "string"
}

Update certificate

PUT /certificates/{certificate-id}

Updates details of the existing certificate published to Gotransverse by the associated UUID.

A payload for updating certificate details.

certificate-id: string
in path

The UUID of the certificate.

Request Content-Types: application/json
Request Example
{
  "name": "string",
  "description": "string",
  "certificate_chain": "string",
  "private_key": "string",
  "key_algorithm": "string",
  "application_types": [
    "string"
  ]
}

Success

401 Unauthorized

Authentication failed.

403 Forbidden

Access denied.

404 Not Found

Entity not found.

422 Unprocessable Entity

Validation failure.

Response Content-Types: application/json
Response Example (200 OK)
{
  "created_on": "string (date-time)",
  "uploaded_on": "string (date-time)",
  "valid_from": "string (date-time)",
  "valid_to": "string (date-time)",
  "name": "string",
  "status": "string",
  "description": "string",
  "certificate_chain": "string",
  "key_algorithm": "string",
  "application_types": [
    "string"
  ],
  "id": "string"
}
Response Example (401 Unauthorized)
{
  "code": "string",
  "message": "string"
}
Response Example (403 Forbidden)
{
  "code": "string",
  "message": "string"
}
Response Example (404 Not Found)
{
  "code": "string",
  "message": "string"
}
Response Example (422 Unprocessable Entity)
{
  "code": "string",
  "message": "string"
}

Delete certificate

DELETE /certificates/{certificate-id}

Removes an existing certificate published to Gotransverse by the associated UUID.

certificate-id: string
in path

The UUID of the certificate.

200 OK

Success

401 Unauthorized

Authentication failed.

403 Forbidden

Access denied.

404 Not Found

Entity not found.

422 Unprocessable Entity

Validation failure.

Response Content-Types: application/json
Response Example (200 OK)
{
  "level": "string",
  "message": "string"
}
Response Example (401 Unauthorized)
{
  "code": "string",
  "message": "string"
}
Response Example (403 Forbidden)
{
  "code": "string",
  "message": "string"
}
Response Example (404 Not Found)
{
  "code": "string",
  "message": "string"
}
Response Example (422 Unprocessable Entity)
{
  "code": "string",
  "message": "string"
}

Activate certificate

POST /certificates/{certificate-id}/activate

Activates an existing certificate associated with the specified UUID.

certificate-id: string
in path

The UUID of the certificate.

200 OK

Success

401 Unauthorized

Authentication failed.

403 Forbidden

Access denied.

404 Not Found

Entity not found.

Response Content-Types: application/json
Response Example (200 OK)
{
  "level": "string",
  "message": "string"
}
Response Example (401 Unauthorized)
{
  "code": "string",
  "message": "string"
}
Response Example (403 Forbidden)
{
  "code": "string",
  "message": "string"
}
Response Example (404 Not Found)
{
  "code": "string",
  "message": "string"
}

Suspend certificate

POST /certificates/{certificate-id}/suspend

Suspends an existing certificate associated with the specified UUID.

certificate-id: string
in path

The UUID of the certificate.

200 OK

Success

401 Unauthorized

Authentication failed.

403 Forbidden

Access denied.

404 Not Found

Entity not found.

Response Content-Types: application/json
Response Example (200 OK)
{
  "level": "string",
  "message": "string"
}
Response Example (401 Unauthorized)
{
  "code": "string",
  "message": "string"
}
Response Example (403 Forbidden)
{
  "code": "string",
  "message": "string"
}
Response Example (404 Not Found)
{
  "code": "string",
  "message": "string"
}

Schema Definitions

ReadCertificate:

The response payload for retrieving certificates within the Gotransverse application.

created_on: string (date-time)

The date time and when the certificate was first published.

uploaded_on: string (date-time)

The date and time and when the public certificate_chain and private_key fields were updated.

valid_from: string (date-time)

The date since when the certificate is valid.

valid_to: string (date-time)

The date until when the certificate is valid.

Example
{
  "created_on": "string (date-time)",
  "uploaded_on": "string (date-time)",
  "valid_from": "string (date-time)",
  "valid_to": "string (date-time)",
  "name": "string",
  "status": "string",
  "description": "string",
  "certificate_chain": "string",
  "key_algorithm": "string",
  "application_types": [
    "string"
  ],
  "id": "string"
}

Error: object

code: string

A code for the specific error. Used to help in determining possible root causes of an error.

message: string

A message providing additional detail for an error.

Example
{
  "code": "string",
  "message": "string"
}

CreateCertificate:

Publishes a new certificate to the Gotransverse application.

private_key: string

The private key.

Example
{
  "private_key": "string",
  "name": "string",
  "status": "string",
  "description": "string",
  "certificate_chain": "string",
  "key_algorithm": "string",
  "application_types": [
    "string"
  ]
}

UpdateCertificate: object

Updates an existing certificate published to the Gotransverse application.

name: string

The name of the certificate.

description: string

The description of the certificate.

certificate_chain: string

The chain of certificates.

private_key: string

The private key.

key_algorithm: string RSA2048

The algorithm of the key.

application_types: ApplicationType

Types of Gotransverse applications where the certificate can be applied such as EXTERNAL_APPLICATION.

ApplicationType
Example
{
  "name": "string",
  "description": "string",
  "certificate_chain": "string",
  "private_key": "string",
  "key_algorithm": "string",
  "application_types": [
    "string"
  ]
}

Message: object

level: string INFO, WARN, DEBUG

A level for the specific message.

message: string

A message providing additional detail for message.

Example
{
  "level": "string",
  "message": "string"
}

EntityUUID: object

The UUID of the entity.

id: string

The internal ID for this entity representation.

Example
{
  "id": "string"
}

Certificate: object

A representation of the certificate used in the Gotransverse application.

name: string

The name of the certificate.

status: string ACTIVE, SUSPENDED

The status of the certificate.

description: string

The description of the certificate.

certificate_chain: string

The chain of certificates.

key_algorithm: string RSA2048

The algorithm of the key.

application_types: ApplicationType
ApplicationType
Example
{
  "name": "string",
  "status": "string",
  "description": "string",
  "certificate_chain": "string",
  "key_algorithm": "string",
  "application_types": [
    "string"
  ]
}

ApplicationType: string

Types of Gotransverse applications where the certificate can be applied.

string EXTERNAL_APPLICATION