---
title: "Share Grant Endpoint"
method: POST
path: "/share/{component}"
tags: ["Share"]
---

# Share Grant Endpoint

`POST /share/{component}`

## Request

- Base URL: `https://api.pharia.example.com`
- URL: `https://api.pharia.example.com/share/{component}`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/aleph-alpha/apis/stateful-responses/docs/share/:component/post.ts> (a function with typed inputs; its response is checked against the schema)

POST /share/{component} — grant (or widen) access to an object.

Gated by ``can_share`` and the escalation ladder in the domain layer; every
ACL write goes through the :class:`AuthorizationPort`. Audited on all paths.

## Path parameters

- `component` 'skill' | 'skill_version' | 'application', required

## Request body

- ShareGrantRequest: POST /share/{component} body — grant (or widen) access to an object. ``object_id`` is the id of the object of the path's component; addressed generically as ``{component}:{object_id}``.
  - `object_id` string, required
  - `users` string[], nullable
  - `organization` string, nullable
  - `public_scope` 'org' | 'tenant' | 'everyone' | 'app': Public-visibility scopes accepted by the ``/share`` API request body. This is the *externally documented* contract (``docs/planning/openfga-skills-authz.md``, "CRUD: /share/skills": ``public_scope: "org" | "tenant" | "everyone" | "app"``) — deliberately distinct from the internal :class:`UserType`, which names OpenFGA subject types (``organization`` / ``tenant`` / ``public`` / ``application``). Keeping them separate stops the internal enum leaking into the public API; :meth:`to_user_type` maps a scope onto the userset :class:`UserType` the domain layer expects. ``app`` makes a skill viewable (read-only) to everyone connecting through the caller's *own* application; it is OpenFGA-only (the Postgres owner/public subset rejects it).
  - `permission` 'owner' | 'editor' | 'viewer' | 'shared_in_app' | 'pharia-ai-admin', required: Assignable roles on the skill / tenant / organization types. These are the only relations that may be written as tuples. The computed permissions (``can_admin``, ``can_view``, etc.) are never written as tuples, only queried via :meth:`AuthorizationPort.check`.

## Response `200`

Successful Response

- unknown

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `413`: Content Too Large
- `422`: Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically.
- `425`: Too Early
- `500`: Internal Server Error
- `501`: Not Implemented
- `502`: Bad Gateway
- `504`: Gateway Timeout

---

[API](https://skmtc.dev/aleph-alpha/apis/stateful-responses.md) - [All operations](https://skmtc.dev/aleph-alpha/apis/stateful-responses/llms.txt) - [OpenAPI document](https://skmtc.dev/aleph-alpha/apis/stateful-responses/revisions/2747297acb54?raw)