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 List the fleets the key can reach, and read alerts, command audit entries, events, mission runs, and utilization.
fleet:write Acknowledge alerts.
robots:read Read robots, capabilities, settings, tracked objects, and supported remote configuration.
robots:write Edit robots, send robot commands and settings, manage tracked objects, and issue a fleet-wide stop.
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, enable or disable missions, 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 identifies the key and the permissions it carries:

{
  "actorType": "api_key",
  "apiKeyId": "key-uuid",
  "orgId": "org-uuid",
  "fleetId": null,
  "permissions": ["fleet:read", "robots:read", "missions:write"]
}

orgId is the organization id for later calls. fleetId is the key's bound fleet, or null when the key may call any fleet in that organization that its permissions allow.

GET /v1/orgs/{org_id}/fleets requires fleet:read. The path organization must be the key's orgId. The response is the fleets that key can use, each as fleetId and name. A fleet-scoped key receives only its bound fleet. See Fleets.

Every later call checks the same key. The key must be unrevoked and unexpired, the organization must match, a fleet-scoped key must be used on its own fleet, and permissions must include the permission named for that endpoint. Otherwise the response is 403 forbidden.

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.