Skip to main content

Command Line tool

Installing the CLI​

To install the CLI (using macOS as an example), download the compiled binary for your architecture using curl and install it as shown below:

sudo curl https://get.antimatter.io/cli/darwin/arm64/am -o /usr/local/bin/am
sudo chmod a+x /usr/local/bin/am

Supported Platforms​

We currently support the following platforms and architectures:

Documentation and Help​

For the latest CLI documentation and detailed command usage, refer to the built-in help system. Use the -h flag for a summary of options or --help for comprehensive information on each command.

am --help
am is a command line utility for managing Antimatter objects and configuration.

Please see the subcommand help text for more information.

Usage: am [COMMAND]

Commands:
  encapsulate        Encapsulate data and optionally save it to a capsule file
  open               Retrieve data from a capsule
  capability         Manage capabilities
  capsule            Manage capsules
  config             Manage configuration for the the antimatter command line tool
  domain             Manage domains
  fact               Manage facts and fact types
  idp                Manage identity providers
  key                Manage external root encryption keys
  peer               Manage domain peers
  policy             Manage policies rules
  read-context       Manage read contexts
  write-context      Manage write contexts
  disaster-recovery  Disaster recovery commands
  data-policy        Manage data policies
  help               Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

Authentication​

Overview​

The Antimatter platform supports multiple forms of authentication, accommodating both specific domain actions and global operations across the platform. Understanding and setting up the appropriate authentication method is crucial for secure and efficient interaction with our services.

Global Identity Authentication​

A global identity allows users to authenticate across the entire platform using credentials from third-party identity providers like Google or Microsoft. This universal authentication is essential for accessing our application website https://app.antimatter.io, where you can manage personal settings and preferences, including favoriting frequently accessed domains.

Creating a Global Identity​

To establish a new global identity, you must authenticate via a recognized provider using a standard OIDC/OAuth process. This process is familiar to most users and involves opening a provided link and then logging into the identity provider as needed. The command to initiate this process is shown below:

am config global login --provider google --name alice_google_account
Please visit https://www.google.com/device and enter the code: ZJXH-TBQK

In the example above, you also set the name for your identity and optionally designate it as the default for commands requiring global authentication.

Domain-Specific Authentication​

For actions restricted to specific domains, Antimatter utilizes both traditional API keys as well as OIDC/OAuth authentication. When you create a domain, the system automatically generates an API key, which can be managed through domain profiles in your configuration file.

Managing Domain Profiles​

Each domain and its corresponding API key are stored as a "profile" in your YAML configuration file located at ~/.antimatter/config (global identities are also stored here). But instead of editing the file manually, you can manage it through the various cli commands. View am config domain --help to see a list of commands available to you.

To create a new domain and set its profile as default:

am domain create --email test@example.com --make-default

To add a new default profile manually using an Antimatter provide API key:

am config domain login --domain-id <DOMAIN> --api-key <API Key>

To add a new default profile using an OAuth identity provider (i.e., google):

am config domain login --domain-id <DOMAIN> --oauth-provider <Provider Name>

Future Authentication Methods​

Looking ahead, we plan to support additional authentication methods, such as integrating Active Directory credentials for domain authentication. This will provide enhanced flexibility and security for enterprise environments.

Self-Service Onboarding​

Overview​

Self-service key onboarding allows you or one of your customers to easily configure your keys in a guided interface online.

am key self-serve --help
Generates a URL for self-service key onboarding in either a single or multi-tenant
model. In the single tenant model, there is only one domain as opposed to the
multi-tenant architecture where you have a "parent" domain that is used for
common configuration and "subdomains" that are unique to each tenant/customer.

By default, the URL is created with a token that expires in an hour meaning the
URL is short-lived. To create a URL that never expires use the `--no-expiration`
flag, and to make a long lived URL, use the --long-expiration flag.

Usage: am key self-serve [OPTIONS] --vendor <vendor>

Options:
      --vendor <vendor>
          Your company name to display in the self-serve URL when someone views the page.

      --nickname <nickname>
          The sub-domain nickname used for a tenant domain. Supplying the `nickname` argument
          implies that you are in a multi-tenant environment and you would like to generate
          a URL for a specific tenant. A nickname is usually the identifier you already
          have for your tenant.

      --alias <alias>
          The sub-domain alias used for a tenant domain. Supplying the 'alias' argument
          implies that you are in a multi-tenant environment and you would like to generate a URL for a
          specific tenant. An alias is the identifier you already have for your tenant.

      --no-expiration
          Creates a URL that does not expire.

      --long-expiration <long-expiration>
          The duration the token should last for. Examples of possible values
          include, but are not limited to, '5h30m30s', '1h', '10000s'

      --with-domain <DOMAIN>
          Override the configured domain with the specified domain ID, while keeping the active API key.

      --profile <PROFILE_NAME>
          Override the domain and API key with those of the configured named profile.

  -h, --help
          Print help (see a summary with '-h')

Single Tenant​

In the single tenant model, a self-service URL is generated for the domain you are logged into. If no profile is specified, this will be the active domain, unless the ANTIMATTER_DOMAIN_ID and ANTIMATTER_API_KEY environment variables are set. If a profile is specified with the --profile argument, that profile from the config file will be used if present.

am key self-serve --vendor "Vendor Display Name"
https://app.antimatter.io/settings/<domain-id>/byok?vendor=Vendor%20Display%20Name&token=<token>

Multi-Tenant​

In the multi-tenant model, a self-service URL is generated for a subdomain (peer domain), using token exchange. The peer domain must be configured to allow token exchange (note that by default, $ am domain create-subdomain will have --link-all set to true, which will permit token exchange).

A subdomain can be referenced by domain ID, alias, or nickname. Use one of these flags when running self-serve, and a self-service URL for your subdomain will be created. For example, generating the self-service URL for a subdomain using the alias would look like:

am key self-serve --vendor "Vendor Display Name" --alias subdomain-alias
https://app.antimatter.io/settings/<subdomain-id>/byok?vendor=Vendor%20Display%20Name&token=<token>

This token will be scoped to the subdomain and will by default be valid for one hour.

Long-lived Tokens​

If a self-serve URL is needed that will be valid for longer than an hour, there are two options for generating a one with a long-lived token. The first is to create a URL with no expiration, using the --no-expiration flag:

am key self-serve --vendor "Vendor Display Name" --no-expiration
https://app.antimatter.io/settings/<domain-id>/byok?vendor=Vendor%20Display%20Name&apikey=<apikey>

⚠️ Security Note ⚠️ The --no-expiration flag will embed the API key for the domain in the self-serve URL. The API key is a permanent password for access to your domain!

Because of this, the --no-expiration flag cannot be used for a subdomain. Trying to use it will result in the following error:

am key self-serve --vendor "Vendor Display Name" --no-expiration --alias subdomain-alias
error: Cannot generate non-expiring self-serve domain for a peered domain - this would leak the parent API key.

To generate a non-expiring self-serve link for the peered domain use the --profile <peer domain id> flag, or run
`am config domain login --domain-id <peer domain id> --api-key <peer api key>`

The second method for generating a self-serve URL with a long-lived token is to use the --long-expiration flag. This is a time duration string that specifies the length of time the token should be valid for. This is particularly useful in the multi-tenant case where you are supplying your customer with an onboarding URL for setting up their keys, and they may not perform this operation immediately.

The duration string is formatted as numbers and time units, such as hours (h), minutes (m), and seconds (s). Examples of valid values include, but are not limited to, '5h30m30s', '1h', '10000s'.

am key self-serve --vendor "Vendor Display Name" --long-expiration 8h
https://app.antimatter.io/settings/<subdomain-id>/byok?vendor=Vendor%20Display%20Name&token=<token>

The above command would generate a self-serve URL that will be valid for 8 hours.

Domain Settings for Token Lifetimes​

The default server configuration for domain token lifetimes is 4 hours. The default maximum domain token lifetime is 12 hours. Trying to generate a long-lived self-serve URL above that default will yield the following result:

am key self-serve --vendor "Vendor Display Name" --long-expiration 120h --alias subdomain-alias
error: creating API configuration: error in response: status code 400 Bad Request: field 'tokenLifetime',
message 'token lifetime was set or derived as 120h0m0s, but maximum token lifetime was set or derived as 8h0m0s'

Domain settings provide a way to both allow --long-expiration times greater than (or less than) 12 hours, and to set default domain token lifetimes to a custom duration.

am domain settings update --help
Update the administrative settings for the domain

Usage: am domain settings update [OPTIONS]

Options:
      --display-name <display-name>
          The text to display when viewing the domain
      --default-token-lifetime <default-token-lifetime>
          The default duration a domain token should last for. Examples of possible values
          include, but are not limited to, '5h30m30s', '1h', '10000s'
      --with-domain <DOMAIN>
          Override the configured domain with the specified domain ID, while keeping the active API key.
      --maximum-token-lifetime <maximum-token-lifetime>
          The maximum duration a domain token should last for. Attempts to authenticate
          with a longer token lifetime will fail. Examples of possible values include, but are not limited to, '5h30m30s',
          '1h', '10000s'
      --profile <PROFILE_NAME>
          Override the domain and API key with those of the configured named profile.
  -h, --help
          Print help

Both --default-token-lifetime and --maximum-token-lifetime take the same duration string format as the --long-expiration flag for self-serve. To view the current specific domain configuration, use $ am domain settings list. Note:

  • defaultTokenLifetime and maximumTokenLifetime will not appear in the response if the server defaults are being used.
  • The duration of defaultTokenLifetime and maximumTokenLifetime will be in seconds

Configure External Root Encryption Key​

The Root Encryption Key can also be configured directly with the CLI using the am key commands.

To list the Root Encryption Keys:

am key list
- source: default
  resourcePath: ''
  rekID: 00000000-0000-0000-0000-000000000000
  description: ''
  imported: false

To see the current active Root Encryption Key:

am key get-active
source: default
resourcePath: ''
rekID: 00000000-0000-0000-0000-000000000000
description: ''
imported: false

A newly created domain will only have the default Root Encryption Key, generated and held by Antimatter. There are various options to create a new Root Encryption Key. Various cloud KMS platforms are supported, including AWS, GCP, and Azure. A 'bring your own key' (byok) option is also supported, where only key material needs to be supplied.

The cloud KMS platforms each support 'sa' and 'am' options, where 'sa' is configured with your service account, and 'am' is delegated to Antimatter's service account.

The key creation options are as follows:

am key create --help
Create a root encryption key

Usage: am key create [OPTIONS] --description <description> --provider <provider>

Options:
      --description <description>
          a description of the key
      --provider <provider>
          the service provider of the key [possible values: aws_sa, gcp_sa, azure_sa, aws_am, gcp_am, azure_am, byok]
...

Assume you have a key named 'mykey' you want to use as your Root Encryption Key. First, create a new Root Encryption Key for the domain:

am key create byok --description "my key" --key-file "path/to/mykey"
rekID: 11111111-1111-1111-1111-111111111111

Now this new key will appear in the list of Root Encryption Keys:

am key list
- source: byok
  resourcePath: byok/11111111-1111-1111-1111-111111111111
  rekID: 11111111-1111-1111-1111-111111111111
  description: my key
  imported: false
- source: default
  resourcePath: ''
  rekID: 00000000-0000-0000-0000-000000000000
  description: ''
  imported: false

To set this as the active Root Encryption Key, run:

am key set-active --id 11111111-1111-1111-1111-111111111111

You can see that this is now the active key:

am key get-active
source: byok
resourcePath: byok/11111111-1111-1111-1111-111111111111
rekID: 11111111-1111-1111-1111-111111111111
description: test description
imported: false

Finally, rotate the Key Encryption Keys:

am key rotate
Key Encryption Keys rotated
All KEKs are now encrypted with the active Root Encryption Key