# Get grant **Endpoint:** `GET /v2/prism/{teamId}/{objectType}/{objectId}/grant` **Operation ID:** `getGrant` **Server:** `https://developers.micro.so` **Security:** `[{"apiKey":[]}]` ## Parameters ```json [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "objectType", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/GrantObjectType" } }, { "name": "objectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] ``` ## Request body ```json null ``` ## Responses ```json { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "500": { "$ref": "#/components/responses/InternalError" } } ``` ## Referenced components ```json { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Public API key generated from Micro settings. Sent as the `x-api-key` header and validated by AWS API Gateway in front of the service." } }, "schemas": { "GrantObjectType": { "type": "string", "description": "Object types whose per-record access grants can be managed. Adds `message` to the CRUD-capable `ObjectType` set: messages are owned by the Gmail sync pipeline and have no create/update/delete surface, but their access rows can still be read and written.", "enum": [ "comment", "deal", "engagement", "identity", "ai_chat_thread", "ai_chat_message", "agent_site", "document", "action", "event", "organization", "contact", "message" ] }, "GrantResponse": { "type": "object", "description": "The grants on a record. For `message`, also carries the entity ids of everyone on the message, resolved from its address headers when the grant was written. The id arrays are read-only and are null when participant resolution was unavailable (for example the mailbox had no Gmail token at the time).", "properties": { "user_id": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/LevelEnum" } }, "team_id": { "type": "object", "propertyNames": { "type": "string", "format": "uuid" }, "additionalProperties": { "$ref": "#/components/schemas/LevelEnum" } }, "group_id": { "type": "object", "propertyNames": { "type": "string", "format": "uuid" }, "additionalProperties": { "$ref": "#/components/schemas/LevelEnum" } }, "share_level": { "$ref": "#/components/schemas/ShareLevel" }, "contact_ids": { "type": [ "array", "null" ], "readOnly": true, "items": { "type": "string", "format": "uuid" } }, "identity_ids": { "type": [ "array", "null" ], "readOnly": true, "items": { "type": "string", "format": "uuid" } }, "organization_ids": { "type": [ "array", "null" ], "readOnly": true, "items": { "type": "string", "format": "uuid" } } } }, "LevelEnum": { "type": "string", "enum": [ "a", "r", "w" ] }, "ShareLevel": { "type": "string", "description": "How much of the record the grant exposes. `metadata` shares only the record's headers and participants; `full` shares its contents. Currently recorded on the access row and returned on read — it is not yet enforced by the read path. Applies to `message` grants; ignored for other object types.", "default": "metadata", "enum": [ "metadata", "full" ] }, "Error": { "type": "object", "description": "Canonical JSON error envelope for every non-2xx v2 API response. `error.code` is the machine-readable error code, `error.message` is the human-readable summary, and `error.request_id` identifies the request for support. When supplied, `error.errors` contains field-level validation issues.", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on the HTTP status, to handle specific failure modes.", "example": "invalid_request" }, "message": { "type": "string", "description": "Human-readable summary suitable for logs. Not localized; do not display verbatim to end users." }, "request_id": { "type": [ "string", "null" ], "description": "Echo of the x-request-id response header. Include in support requests." }, "errors": { "type": "array", "description": "Optional structured field-level validation issues when the server provides them.", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "JSON path of the offending property (e.g. \".body.default.email\")." }, "message": { "type": "string" }, "code": { "type": "string", "description": "Validator-specific code (e.g. \"required.openapi.validation\")." } }, "required": [ "message" ] } }, "details": { "type": "object", "description": "Optional bag of error-specific context. Shape varies by code; clients should treat fields as opaque unless documented." } } } } } }, "headers": { "XRequestId": { "description": "Correlation ID. Echoed from the request `x-request-id` header when supplied, otherwise generated. Include in support requests.", "schema": { "type": "string" } } }, "responses": { "Unauthorized": { "description": "Missing or invalid credentials. API Gateway maps a missing or invalid `x-api-key` to HTTP 401 with this envelope (including `request_id`). A 403 here means the key was accepted but the caller is not permitted.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "Authenticated but not permitted to perform this action.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Resource or route does not exist.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "MethodNotAllowed": { "description": "The HTTP method is not permitted on this resource. Returned both when the route exists but does not accept the verb, and when the underlying object cannot accept the operation (e.g., pipeline-managed objects cannot be deleted). Branch on `error.code` to distinguish.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "InternalError": { "description": "Unexpected server error. Retry with backoff; report `request_id` if persistent.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } ```