> ## Documentation Index
> Fetch the complete documentation index at: https://docs.artbucket.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Change where an agent you connected works

> Its workspaces and its scope, as the consent screen gives them: the scope is brought down, in each workspace, to the most you may give there. It keeps its secret, so the agent doesn't sign in again. Only your own agents.

Scope: `read`.



## OpenAPI

````yaml /openapi.json patch /api/v1/keys/{id}
openapi: 3.1.0
info:
  title: artbucket
  version: '1'
  description: >-
    Agent-first asset management. The web UI is built on this API and nothing
    else, beside signing in at /api/auth. Send `Authorization: Bearer <key>`: a
    key works in one workspace with one scope, and scopes are a ladder: read <
    propose < write < admin. People signed in to the app carry a session cookie
    instead, and their scope is what their grants add up to: on the
    organization, the workspace, or single collections and assets. A scope shown
    as needed on the workspace is also enough on the one collection or asset a
    route acts on. Agents (MCP at POST /api/v1/mcp) usually get `propose`: what
    they add waits for a human.
servers:
  - url: http://localhost:3000
security:
  - bearer: []
  - session: []
  - {}
paths:
  /api/v1/keys/{id}:
    parameters:
      - name: id
        in: path
        required: true
        description: Key id
        schema:
          type: string
    patch:
      summary: Change where an agent you connected works
      description: >-
        Its workspaces and its scope, as the consent screen gives them: the
        scope is brought down, in each workspace, to the most you may give
        there. It keeps its secret, so the agent doesn't sign in again. Only
        your own agents.


        Scope: `read`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                workspaces:
                  minItems: 1
                  maxItems: 100
                  type: array
                  items:
                    type: string
                    format: uuid
                    pattern: >-
                      ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                scope:
                  type: string
                  enum:
                    - propose
                    - read
                    - write
              required:
                - workspaces
                - scope
              additionalProperties: false
      responses:
        '200':
          description: The agent, as it is now
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                        pattern: >-
                          ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                      name:
                        type: string
                      workspaces:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              format: uuid
                              pattern: >-
                                ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            name:
                              type: string
                            organization:
                              type: string
                            scope:
                              type: string
                              enum:
                                - read
                                - propose
                                - write
                                - admin
                          required:
                            - id
                            - name
                            - organization
                            - scope
                          additionalProperties: false
                        description: >-
                          Where it works, the first where a call without
                          `workspace` goes
                      givable:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              format: uuid
                              pattern: >-
                                ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            name:
                              type: string
                            organization:
                              type: string
                            max:
                              type: string
                              enum:
                                - propose
                                - read
                                - write
                          required:
                            - id
                            - name
                            - organization
                            - max
                          additionalProperties: false
                        description: >-
                          Every workspace you could give it, with the most you
                          may give there
                    required:
                      - id
                      - name
                      - workspaces
                      - givable
                    additionalProperties: false
                required:
                  - data
                additionalProperties: false
        default:
          description: An error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      detail: {}
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
components:
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: 'An API key: ab_...'
    session:
      type: apiKey
      in: cookie
      name: better-auth.session_token
      description: Signed in, at /api/auth

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.