Authentication and API keys

The Observiant API authenticates every request with an API key sent as a bearer token. API keys belong to your Organization, not to the person who created them. Each key works only with your Organization's environment, never expires, and keeps working until you revoke it.

What an API key can do

An API key can read and change the resources documented in this section:

• list, create, update and delete targets, and assign them to agents
• read latency and loss, traceroutes, path changes and correlated events

A key cannot sign in to the dashboard, run on-demand ping or MTR tests, or manage agents, sub-users, plans or billing. Requests to any other endpoint return 403 Forbidden.

warning

An API key can delete targets, and deleting a target permanently removes its measurement history. Store keys as carefully as you store device credentials.

Create an API key

You need the Owner or Admin role in your Organization.

1. Sign in to the customer portal at my.observiant.com.
2. Open Organization and scroll to API keys.
3. Enter a Key label that says where the key will be used, for example ansible-prod or netbox-sync. Labels can be up to 120 characters and must be unique among your Organization's active keys, ignoring case.
4. Enter your Current password. If your sign-in uses two-factor authentication, also enter a code from your authenticator app or an unused recovery code.
5. Select Create API key.
6. Copy the secret that appears and store it in your secret manager. The portal shows the secret only once. If you lose it, revoke the key and create a new one.

An Organization can have up to 20 active keys. The API keys table lists each key's label, the last 8 characters of its secret (Ending), when it was created and when it was last used.

Key format

A key is a 78-character string with the prefix obs_api_:

obs_api_<key ID>_<secret>

Treat the whole string as an opaque secret. The fixed prefix lets secret scanners and pre-commit hooks recognize keys that have been committed by mistake.

Make authenticated requests

Send the key in the Authorization header with the Bearer scheme, over HTTPS, to your environment's address:

GET /api/targets HTTP/1.1
Host: example.observiant.com
Authorization: Bearer obs_api_…

The examples in this documentation read the environment address and the key from environment variables, so neither appears in scripts or shell history. Replace example with your environment's subdomain:

export OBSERVIANT_URL="https://example.observiant.com"
# Paste the key and press Enter. Nothing is shown while you type.
read -rs OBSERVIANT_API_KEY && export OBSERVIANT_API_KEY

Verify the key by listing your targets. A working key returns 200 OK and a JSON array:

curl

curl --header "Authorization: Bearer $OBSERVIANT_API_KEY" \
  "$OBSERVIANT_URL/api/targets"

Python

This example uses the Requests library (pip install requests).

import os

import requests

base_url = os.environ["OBSERVIANT_URL"]
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['OBSERVIANT_API_KEY']}"

response = session.get(f"{base_url}/api/targets", timeout=30)
response.raise_for_status()
for target in response.json():
    print(target["target_id"], target["protocol"], target["host"], target["label"])

Ansible

Keep the key in Ansible Vault or your secret store, and pass it to the play as a variable:

- name: List Observiant targets
  hosts: localhost
  gather_facts: false
  vars:
    observiant_url: https://example.observiant.com
    observiant_api_key: "{{ vault_observiant_api_key }}"
  tasks:
    - name: Read targets
      ansible.builtin.uri:
        url: "{{ observiant_url }}/api/targets"
        headers:
          Authorization: "Bearer {{ observiant_api_key }}"
        return_content: true
      register: observiant_targets

    - name: Show target labels
      ansible.builtin.debug:
        msg: "{{ observiant_targets.json | map(attribute='label') | list }}"

How requests are authorized

Observiant checks every request before it reaches your environment. A request is accepted only if all of the following are true:

• The Authorization header contains exactly Bearer followed by an active key.
• The key belongs to the Organization that owns the environment at the requested address.
• The environment is running and your Organization's plan is active.
• The method and path are among the endpoints available to API keys.

Revoking a key takes effect on the next request. Any request that includes an Authorization header is treated as an API-key request: other schemes, such as HTTP Basic, are rejected, and dashboard session cookies are ignored.

Troubleshooting

Authorization failures return an empty body, so check the status code:

Status	Meaning	What to check
401 Unauthorized	The key is missing, malformed, revoked, or belongs to another Organization.	The header is Authorization: Bearer <key> with a single space. The key was copied in full, 78 characters. The key is still listed in the portal. The address is your own environment's.
403 Forbidden	The key is valid, but this endpoint or method is not available to API keys.	The method and path against the endpoint list.
404 Not Found	The address is not an active Observiant environment.	The environment subdomain, and that the portal shows your environment as running.
503 Service Unavailable	Authorization is temporarily unavailable.	Retry with exponential backoff.

To see the status code with curl, add --include, or use --write-out '%{http_code}\n'.

After authorization succeeds, the API itself can still reject a request. Those errors include a JSON body, as described in Errors.

Rotate a key

Keys do not expire, so rotate them on your own schedule and whenever a key might have been exposed:

1. Create a new key with a label that tells it apart from the old one, for example netbox-sync-2026-10.
2. Deploy the new key to every system that uses the old one.
3. In the API keys table, confirm that Last used advances for the new key and stops changing for the old one. Last used is updated at most once a minute.
4. Revoke the old key.

Revoke a key

In the portal, open Organization, find the key in the API keys table and select Revoke. Requests that use the key fail with 401 Unauthorized from that point on. A revoked key cannot be restored.

Keys stay active when the person who created them leaves your Organization. Review the API keys table whenever someone with access to your keys leaves.

Recommendations

• Create a separate key for each integration so that you can rotate or revoke one without affecting the others.
• Store keys in a secret manager, Ansible Vault or your CI system's secret store. Never put them in source control, URLs or log output.
• Use the key only in the Authorization header and only over HTTPS.