# Members & roles

An account can have several people. Each signs in with their own email address and password and has one role.
API keys, webhooks and OAuth apps belong to the account, never to a person, so nothing stops working when
someone leaves.

## Roles

| What the person can do | Owner | Admin | Developer | Viewer |
|---|---|---|---|---|
| Read everything of the account: leads, offers, earnings, settings | ✓ | ✓ | ✓ | ✓ |
| Change leads, listings, photos, offers, reservations, the search profile, the profile and logo; accept terms | ✓ | ✓ | – | – |
| API keys, webhooks, OAuth apps, request logs, usage, audit log | ✓ | ✓ | ✓¹ | – |
| Invite people, change roles, remove people | ✓ | ✓ | – | – |
| See and change payout details | ✓ | – | – | – |
| Leave the account | – | ✓ | ✓ | ✓ |

¹ A developer creates, rolls and revokes only keys with read scopes plus `keys:manage`, `webhooks:manage`,
`usage:read` and `audit:read` — never a key that writes, manages members or OAuth apps, or reads earnings. The key
policy (maximum key age, revoking unused keys) is for owners and admins.

The **owner** is the login the account was created with. There is exactly one. Nobody can remove or demote the
owner, and the owner cannot leave. An admin manages everyone else, including other admins; nobody changes their
own role.

## How someone joins

1. An owner or admin invites an email address with a role: in the portal (Settings → Members) or with
   `POST /v1/members`.
2. Creator Guard shows a join link `https://app.creator-guard.com/join/…` **once**. It is valid for 48 hours.
   Send it to the person yourself — Creator Guard sends no email. **Whoever opens the link first sets the password
   for this address**, so send it only through a channel the person controls.
3. The person opens the link. Without a Creator Guard login yet, they choose a password for **exactly that email
   address** on the join page and the login is created; with an existing login for that address, they sign in and
   accept. From then on they work in the account with their role.

A link works once and stops working when it is accepted, revoked or expired. A login belongs to one account only:
the owner or a member of another account, a creator login and Creator Guard staff cannot join. Inviting such an
address looks exactly like any other invitation — in the portal and over the API (`201` with a `join_url`), listed
and revocable like the others, and its join page looks the same — but it can never be accepted. So an invitation
tells you nothing about what kind of login an address has. If someone reports that they cannot accept a new link
although they signed in with the invited address, they probably already belong to another account. Inviting the same
address again creates a new link and retires the old one, in the portal and over the API. An account can send at
most 20 invitations in 24 hours; every invitation counts, including those whose link cannot be used.

A login created on the join page is shown as **unverified** ("login created via invitation link — email not
verified", `email_verified: false` in the API): the person proved only that they had the link. When such a person
is removed or leaves and belongs to no other account, their login is deleted, so the address is free for its
owner again.

Member changes in the portal need two-factor authentication. An API key with `members:manage` acts for the account
and needs none — treat it like a password. Over the API you invite developers and viewers; admins are invited in the
portal.

## With the API

All three operations need the scope `members:manage` and a live key. A `cg_test_` key gets `404 not_found`
("Members are managed in live mode."), because test mode has no logins. Member management works before the terms
are accepted.

List the people and open invitations (owner first, not paginated):

```bash
curl https://api.creator-guard.com/v1/members \
  -H "Authorization: Bearer $CG_KEY"
```

Invite someone:

```bash
curl -X POST https://api.creator-guard.com/v1/members \
  -H "Authorization: Bearer $CG_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"email": "dev@example.com", "role": "developer"}'
```

The answer is the invitation with `join_url`. Pass the link on and do not store it: it is not shown again — a retry
with the same `Idempotency-Key` within 24 hours returns the same invitation with `join_url: null`. Lost the link?
Delete the invitation and invite again.

```json
{
  "object": "member",
  "id": "inv_eaaaaaaaabaabaaaaaaaaaaaae",
  "email": "dev@example.com",
  "role": "developer",
  "status": "invited",
  "created_at": "2026-10-13T09:00:00Z",
  "email_verified": null,
  "expires_at": "2026-10-15T09:00:00Z",
  "join_url": "https://app.creator-guard.com/join/7c4e…"
}
```

Remove a person (`mem_…`) or revoke an invitation (`inv_…`):

```bash
curl -X DELETE https://api.creator-guard.com/v1/members/inv_eaaaaaaaabaabaaaaaaaaaaaae \
  -H "Authorization: Bearer $CG_KEY"
```

## When someone leaves

Removing a person (portal or API), their leaving, and lowering their role all happen in one step with what they
could still use:

- their open invitations are revoked (also when an admin becomes developer or viewer);
- every API key whose secret they had — keys they created or rolled in the portal, and keys those keys created over
  the API — is revoked (`revoked_reason: member:removed`); after a downgrade only the keys above the new role
  (`member:role_changed`);
- webhook endpoints whose current signing secret they know (removal, or a downgrade to viewer) get a new secret that
  nobody has seen and are disabled. Roll the secret in the portal, put the new one into your receiver and enable the
  endpoint again — until then your receiver should reject anything signed with the old secret.

Their login then acts for no account from its next request on. Deleting the owner answers `409 invalid_state` with
`current_state: owner`. Roles are changed in the portal; the API invites and removes.

Every change is recorded in the audit log (`GET /v1/audit-events`): `member.invited`, `member.joined`,
`member.role_changed`, `member.removed`, `member.invitation_revoked`, `member.login_email_changed` (a member
changed the email address of their own login; no address in the entry, the owner's own change is not listed).
