Overview

Termius API Bridge is a REST API that enables you to create and delete hosts as well as create groups in your Termius vaults. 

The API is designed to be secure and to be deployed to you environment as a Docker image. It provides only write operations and cannot read data in your vault. It uses the same encryption schema as Termius apps and data are in sync with your Termius Vault.

API Example

A Curl example of the request to create a host:

curl -X 'POST' \
  'http://termius-api.acme.com/v1/host/i-1234567890abcdef0/' \
  -H 'Content-Type: application/json' \
  -d '{"vault": "Team", "address": "example.com", "label": "Database"}'

termius-api.acme.com is the address of your API Bridge instance deployed in your environment.

The complete OpenAPI specification. 

Use Cases

The API Bridge is designed for synchronizing your infrastructure with Termius vault. The primary use case is automatically adding and removing hosts in your Termius vaults as these hosts are launched and terminated. E.g., adding a new host when AWS Autoscaling Group launches a new EC2 instance.

Bring Hosts into Termius Vaults

Creating a New Host. When a new Virtual machine or server is provisioned in your infrastructure, call the Create a Host API to create a new host in your Termius vault.

Pass the host ID in your infrastructure as external_id in the API path, the vault name in the vault, address, and optional label fields. Additionally, pass the ssh port in port field inside the ssh object or telnet port in port inside the telnet object.

An example of the request that creates a new host with external_id as vm-1234 in Team vault with address example.com, label Database, and ssh port 22:

• path: /v1/host/vm-1234/
• body: {"vault": "Team", "address": "example.com", "label": "Database", "ssh": {"port": 22}}

After calling the API, this new host will appear in the Termius app inside the Team vault.

Optionally, pass the group field with the group external_id instead of the vault. Create such a group with the /group/{external_id}/ API.

Deleting a host. When a Virtual machine or server is de-provisioned in your infrastructure, call the Delete a Host API to delete this host from your Termius vault.

Pass the host id in your infrastructure as external_id in the API path.

Example of the request that deletes the host with external_id as vm-1234:

• path: /v1/host/vm-1234/

After calling the API, this new host will disappear from the Termius app.

Register New Clients

Creating a group. When a new client or a project is registered in your infrastructure platform, to keep all hosts bound to them, call the Create a group API.

Pass a vault name in the vault field and the group label.

Example of the request that creates a new group in Team vault with external_id as client-123 and label John Doe:

• path: /v1/group/client-123/
• body: {"vault": "Team", "label": "John Doe"}

After calling the API, this new group will appear in the Termius app inside the Team vault.

Creating a host inside the group. When a new host is created for a client or a project, call the create a Host API with the group external_id passed as group property.

Example of the API payload that creates a new host with external_id as vm-2 inside the group with the external_id as client-123 and address example.com:

• path: /v1/host/vm-2/
• payload: {"group": "client-123", "address": "example.com"}

Configuration

The API Bridge is authenticated for operations in Termius Cloud by the termius-bridge-credentials.json file. Termius does not store this file. It is available only during the creation of the API bridge on https://account.termius.com/bridges.

Security and Encryption

The Public API provides one-way data flow to Vault and uses the same encryption as your Termius app. By controlling Termius Bridge encryption keys and credentials, you control access to the Termius Bridge.

Whenever you notice that the Termius Bridge credentials were compromised, revoke the Termius Bridge credentials, and it will lose access to the Termius Cloud.

Help

If you have any questions about Termius API Bridge please submit a new ticket.