# Get a join link

URL: https://heaven.dev/docs/reference/organizations/link-add
Updated: 2026-11-21

Get an active organization join link or create one that lasts seven days. Anyone who opens the link and signs in can join in its assigned role. The admin link requires the billing owner or an admin with no withheld commands.

`POST /v1/organization/modify`

## Parameters

- `role` (string): Join-link role: user (default) or admin.
- `organization` (string): Organization name or ID. A credential, named resource or sole membership can select the organization for you.

## Returns

- `data` (object, always present): A link granting membership in an organization.
  - `created_at` (string (date-time), always present): When the link was created.
  - `expires_at` (string (date-time), always present): When the link expires.
  - `joined` (integer, always present): Number of people who joined through this link.
  - `link` (string, always present): Claimable URL. Anyone holding it can accept the invitation.
  - `organization` (string, always present): Organization joined through the link.
  - `role` (string, always present): Organization role granted on joining: `user` or `admin`.

## Errors

Each code is explained in full at https://heaven.dev/docs/reference/errors.

| Code | Status | What happened |
|---|---:|---|
| `invalid` | 400 | An input is missing or invalid. |
| `unauthenticated` | 401 | The credential is missing, invalid, expired or revoked. |
| `denied` | 403 | The caller lacks permission for this action. |
| `not_found` | 404 | The resource is absent or inaccessible to this caller. |
| `conflict` | 409 | The request conflicts with the current resource state or an earlier request. |
| `over_capacity` | 409 | The request exceeds a resource or credential allowance. |
| `access_list_full` | 409 | The change would exceed the access-list allowance. |
| `payment_required` | 402 | Payment or credit is required. |
| `rate_limited` | 429 | The caller's request rate exceeds its limit. |
| `busy` | 429 | Too much work is in progress to accept this request. |
| `unknown` | 503 | The outcome is unconfirmed; a change may have happened. |
| `unavailable` | 503 | The service or requested feature is unavailable. |

## Notes

- CLI: `heaven login` with `HEAVEN_API_KEY` unset. MCP: Heaven sign-in. cURL: `HEAVEN_SIGN_IN_KEY` from approved device sign-in (`POST /v1/auth/create`).
- A key limited to a command list cannot run this command.

## Examples

```sh tab="heaven CLI"
heaven organization link add
  [--role ROLE]
  [--organization ORGANIZATION]
```

```sh tab="SSH"
ssh cli@heaven.dev organization link add
  [--role ROLE]
  [--organization ORGANIZATION]
```

```sh tab="cURL"
curl https://heaven.dev/v1/organization/modify \
  -H "Authorization: Bearer $HEAVEN_SIGN_IN_KEY" \
  --json '{"action": "link add", "role": "user", "organization": "acme"}'
```

```json tab="MCP"
{ "tool": "organization_link_add",
  "arguments": { "role": "user", "organization": "acme" } }
```

Response:

```json title="Response excerpt"
{
  "version": 1,
  "data": {
    "created_at": "2026-11-16T12:00:00Z",
    "expires_at": "2026-11-23T12:00:00Z",
    "joined": 0,
    "link": "https://heaven.dev/join/ZDNiNDU5ZWM0MGI4NDI3NTFiM2IwZTFjN2IwMDRkOTE",
    "organization": "acme",
    "role": "user"
  }
}
```
