Skip to content

Authentication

The Rover Nexus REST API accepts API keys as bearer tokens over HTTPS. API keys belong to one organization, may be restricted to one fleet, and carry an explicit permission allowlist.

Base URL and OpenAPI

All documented endpoints are relative to:

https://<your-nexus-host>/v1

The server publishes its OpenAPI 3.1 contract without authentication:

GET /openapi.json

Use the OpenAPI document as the machine-readable source for request and response schemas. The pages in this section explain workflows and compatibility details.

Using an API key

Authorization: Bearer rn_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Never put a key in browser code, a URL, or a public repository. The raw key is shown only once when created.

Permissions

Permission Grants
fleet:read Read alerts, command audit entries, events, mission runs, schedules, and utilization.
fleet:write Acknowledge alerts.
robots:read Read robots, capabilities, settings, and supported remote configuration.
robots:write Edit robots, send robot commands and settings, and manage tracked objects.
features:read Read features and Field Rules.
features:write Author, deploy, and delete features; manage decomposition and Field Rules.
operations:read Read live operation and map context.
operations:control Control the fleet operation and create or cancel scheduled commands.
missions:read Read mission templates and schedules.
missions:write Author templates, submit or schedule jobs, control mission runs, and edit mission priorities or rosters.
history:read Read finished mission history through the Agent API.

The retired operations:draft, operations:validate, operations:deploy, operations:deploy_without_human_approval, audit:read, exports:create, and exports:read permissions no longer authorize an endpoint.

Discovery

GET /v1/me
GET /v1/orgs/{org_id}/fleets

GET /v1/me returns the current actor and permissions. Fleet discovery returns only fleets the actor is allowed to view. A fleet-scoped key sees only its bound fleet.

API-key management endpoints are user-session only. An API key cannot create or revoke other keys. See Organizations.

Idempotency

Durable-resource creation uses an Idempotency-Key header where noted:

Idempotency-Key: <unique value for this logical request>

The key is scoped to the authenticated actor, organization, fleet, endpoint, and request body.

  • The first request claims the key.
  • A concurrent request with the same key returns 409 conflict while the first is running.
  • A completed request with the same key and body replays the original status and body for 24 hours, including across server restarts.
  • Reusing the key with a different body returns 409 conflict.
  • A failed handler releases the claim so it can be retried.

Use a new key for each logical operation. API-key creation requires the header but is intentionally not replayable because its response contains the raw secret.

Request validation

Agent API request objects are strict. Unknown fields, malformed UUIDs, a non-array where an array is expected, or an invalid member inside an array reject the whole request with 400 bad_request. Do not depend on misspelled or malformed fields being ignored.

Errors

Errors use a stable JSON shape:

{ "error": "Human-readable message", "code": "machine_code" }

Some errors add a details object with structured persistence or delivery results.

Status code Meaning
400 bad_request Malformed JSON, path, query, identifier, array, or missing required header.
401 unauthorized Missing, invalid, expired, or revoked credential.
403 forbidden The actor lacks permission or cannot access the organization or fleet.
404 not_found The named resource does not exist or is not visible to the actor.
409 conflict Current state prevents the request, or an idempotency claim conflicts.
207 partial_failure Persistence succeeded but delivery to one or more robots was incomplete. Inspect details.
422 policy_rejected A robot's advertised command policy rejects the command.
429 rate_limited A rate limit was exceeded. Honor Retry-After.
500 internal Unexpected server error.
502 unavailable Every target in a bulk robot command failed.
503 unavailable A live service, robot, or operation result is temporarily unavailable.