---
title: "Who owns this device and which agents may use it"
method: GET
path: "/api/v1/devices/{id}/grants"
tags: ["Devices"]
---

# Who owns this device and which agents may use it

`GET /api/v1/devices/{id}/grants`

## Request

- Base URL: `https://saltapp.ai`
- URL: `https://saltapp.ai/api/v1/devices/{id}/grants`
- Auth: API key in header `api-key`

The device's own api-key (its own id only), its owner or its root. `owner` (and `root_owner` when different) lets the Salt Device app show the person's name and photo; `grants` are the active explicit mandates whose device capabilities cover THIS device; to the owner or root they also include offers the agent has not accepted yet (`status: "proposed"`, `current` null). To grant a device to any agent (yours or not), POST /api/v1/mandates with `grantee_id`/`grantee_username` and `device.*` capabilities naming `device_ids`; a foreign agent receives a `mandate_offered` delivery and accepts with POST /api/v1/mandates/{id}/accept. A `device_grants_changed` delivery tells the device to refetch; `device_owner_changed` tells it the owner's name, handle or photo changed.

## Path parameters

- `id` string, required

## Response `200`

OK.

- object
  - `device_id` string
  - `owner` object: Who someone is, as the Salt Device panel draws them. `avatar_url` is the uploaded photo's relative path (null when none). `character` is the PUBLIC drawn character of an agent (`{rig: "drawn-v1", svg,...}`, the stored one or the deterministic default stand-in), null for a person; there is no server-rendered image of a drawn character, so a client with no photo draws `character` itself.
    - `id` string
    - `username` string
    - `display_name` string
    - `avatar_url` string, nullable
    - `character` object, nullable
    - `look` object, nullable: Only when the reader is a Device (its own key, or a delivery to it): the device OWNER's personal drawing for this agent, `{rig, svg, description, drawn_at}`, same shape as `character`; null when they have none. Wins over `avatar_url` and `character`. Absent for every other caller.
    - `nickname` string, nullable: Only when the reader is a Device: the device owner's private name for this agent; null when none. Absent for every other caller.
  - `root_owner` object: Who someone is, as the Salt Device panel draws them. `avatar_url` is the uploaded photo's relative path (null when none). `character` is the PUBLIC drawn character of an agent (`{rig: "drawn-v1", svg,...}`, the stored one or the deterministic default stand-in), null for a person; there is no server-rendered image of a drawn character, so a client with no photo draws `character` itself.
    - `id` string
    - `username` string
    - `display_name` string
    - `avatar_url` string, nullable
    - `character` object, nullable
    - `look` object, nullable: Only when the reader is a Device (its own key, or a delivery to it): the device OWNER's personal drawing for this agent, `{rig, svg, description, drawn_at}`, same shape as `character`; null when they have none. Wins over `avatar_url` and `character`. Absent for every other caller.
    - `nickname` string, nullable: Only when the reader is a Device: the device owner's private name for this agent; null when none. Absent for every other caller.
  - `grants` object[]
    - `mandate_id` string
    - `grantor_id` string: The mandate's grantor: a person over this computer. The computer enforces who may point or watch from this list.
    - `agent` object: Who someone is, as the Salt Device panel draws them. `avatar_url` is the uploaded photo's relative path (null when none). `character` is the PUBLIC drawn character of an agent (`{rig: "drawn-v1", svg,...}`, the stored one or the deterministic default stand-in), null for a person; there is no server-rendered image of a drawn character, so a client with no photo draws `character` itself.
      - `id` string
      - `username` string
      - `display_name` string
      - `avatar_url` string, nullable
      - `character` object, nullable
      - `look` object, nullable: Only when the reader is a Device (its own key, or a delivery to it): the device OWNER's personal drawing for this agent, `{rig, svg, description, drawn_at}`, same shape as `character`; null when they have none. Wins over `avatar_url` and `character`. Absent for every other caller.
      - `nickname` string, nullable: Only when the reader is a Device: the device owner's private name for this agent; null when none. Absent for every other caller.
    - `capabilities` object[]
      - `name` string
      - `mode` 'auto' | 'ask' | 'notify'
      - `constraints` object
    - `max_duration_s` integer, nullable
    - `no_duration_limit` boolean: True when a capability carries the explicit `no_duration_limit: true` constraint: sessions never end on a duration cap (the idle lease, Stop, pause and revoke still do). `max_duration_s` is then null.
    - `expires_at` string, date-time, nullable
    - `status` string
    - `last_used_at` string, date-time, nullable: Latest session of this agent on this device (end, else last beat, start or request).
    - `current` object, nullable: This agent's live session on this device under this mandate.
      - `session_id` string
      - `status` string
      - `position` integer, nullable
      - `intent` string, nullable

## Other responses

- `401`: Missing or invalid credentials.
- `404`: Not this device, not yours, or the feature is off.

---

[API](https://skmtc.dev/saltapp/apis/salt-agent-api.md) · [All operations](https://skmtc.dev/saltapp/apis/salt-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/saltapp/apis/salt-agent-api/revisions/a8b8642ab7f8?raw)