Organizations

List my organisations

GET /a/v1/organizations/me

Every organisation the signed-in user is a member of, with their role and membership status. current marks the organisation of this session.

Who can call it: Signed-in user only: do this in the Yona app.

Example request

curl https://gp.useyona.com/a/v1/organizations/me \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Responses

Update the current organisation

PATCH /a/v1/organizations/me

Changes the name, contact email, website or address. Changing contactEmail or address also needs the organization.update_contact capability. The response carries the organisation summary plus each contact field that was changed.

Who can call it: Signed-in user only: do this in the Yona app.

Request body

address

Example request

curl -X PATCH https://gp.useyona.com/a/v1/organizations/me \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Trading",
    "contactEmail": "accounts@acme.ng",
    "website": "https://acme.ng"
  }'

Responses

Get the organisation profile

GET /a/v1/organizations/{orgId}

The profile of the organisation the token belongs to. orgId must be that organisation (404 otherwise). Available to users and API keys.

Who can call it: API key or signed-in user.

Parameters

Example request

curl https://gp.useyona.com/a/v1/organizations/me \
  -H "Authorization: Bearer sk_test_your_key_here"

Responses

Update an organisation by id

PATCH /a/v1/organizations/{orgId}

The same update as PATCH /a/v1/organizations/me; orgId must be the organisation of the session (404 otherwise). Changes the name, contact email, website or address. Changing contactEmail or address also needs the organization.update_contact capability. The response carries the organisation summary plus each contact field that was changed.

Who can call it: Signed-in user only: do this in the Yona app.

Parameters

Request body

address

Example request

curl -X PATCH https://gp.useyona.com/a/v1/organizations/me \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Trading",
    "contactEmail": "accounts@acme.ng",
    "website": "https://acme.ng"
  }'

Responses

List members

GET /a/v1/organizations/{orgId}/users

A page of the organisation’s members, filtered by the query.

Who can call it: Signed-in user only: do this in the Yona app.

Parameters

Example request

curl https://gp.useyona.com/a/v1/organizations/me/users \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Responses

Get a member

GET /a/v1/organizations/{orgId}/users/{userId}

Who can call it: Signed-in user only: do this in the Yona app.

Parameters

Example request

curl https://gp.useyona.com/a/v1/organizations/me/users/9f8e7d6c-5b4a-3210-fedc-ba9876543210 \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Responses

Remove a member

DELETE /a/v1/organizations/{orgId}/users/{userId}

Who can call it: Signed-in user only: do this in the Yona app.

Parameters

Example request

curl -X DELETE https://gp.useyona.com/a/v1/organizations/me/users/9f8e7d6c-5b4a-3210-fedc-ba9876543210 \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Responses

Leave the organisation

POST /a/v1/organizations/{orgId}/leave

Ends the caller’s own membership in the organisation.

Who can call it: Signed-in user only: do this in the Yona app.

Parameters

Example request

curl -X POST https://gp.useyona.com/a/v1/organizations/me/leave \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Responses

Transfer ownership

POST /a/v1/organizations/{orgId}/ownership-transfer

Makes another active member the owner. The caller confirms with their password (and a second-factor code when two-factor is on) and becomes an admin unless they choose to stay an owner.

Who can call it: Signed-in user only: do this in the Yona app.

Parameters

Request body

Example request

curl -X POST https://gp.useyona.com/a/v1/organizations/me/ownership-transfer \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "toUserId": "9f8e7d6c-5b4a-3210-fedc-ba9876543210",
    "password": "your-password",
    "code": "104829"
  }'

Responses

Change a member’s role

PATCH /a/v1/organizations/{orgId}/users/{userId}/role

Assigns another system role to the member. Access tokens the member already holds are refused until they refresh, so the new role applies at once.

Who can call it: Signed-in user only: do this in the Yona app.

Parameters

Request body

Example request

curl -X PATCH https://gp.useyona.com/a/v1/organizations/me/users/d8b2e4f6-9a3c-5b7d-0e1f-2a3b4c5d6e7f/role \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "roleId": "9f8e7d6c-5b4a-3210-fedc-ba9876543210"
  }'

Responses

Suspend or restore a member

PATCH /a/v1/organizations/{orgId}/users/{userId}/status

Sets the membership status in this organisation: suspended needs member.suspend, active needs member.restore.

Who can call it: Signed-in user only: do this in the Yona app.

Parameters

Request body

Example request

curl -X PATCH https://gp.useyona.com/a/v1/organizations/me/users/9f8e7d6c-5b4a-3210-fedc-ba9876543210/status \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "suspended"
  }'

Responses

List roles

GET /a/v1/organizations/{orgId}/roles

The system roles a member can hold, each with its capabilities.

Who can call it: Signed-in user only: do this in the Yona app.

Parameters

Example request

curl https://gp.useyona.com/a/v1/organizations/me/roles \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Responses

Get a role

GET /a/v1/organizations/{orgId}/roles/{roleId}

Who can call it: Signed-in user only: do this in the Yona app.

Parameters

Example request

curl https://gp.useyona.com/a/v1/organizations/me/roles/9f8e7d6c-5b4a-3210-fedc-ba9876543210 \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Responses

List available capabilities

GET /a/v1/organizations/{orgId}/roles/permissions/available

Every capability a member can hold, with its label and properties, and the subset an API key may hold.

Who can call it: Signed-in user only: do this in the Yona app.

Parameters

Example request

curl https://gp.useyona.com/a/v1/organizations/me/roles/permissions/available \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Responses

List invitations

GET /a/v1/organizations/{orgId}/invitations

A page of the organisation’s invitations (pending by default). No invitation codes are returned.

Who can call it: Signed-in user only: do this in the Yona app.

Parameters

Example request

curl https://gp.useyona.com/a/v1/organizations/me/invitations \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Responses

Invite someone to the organisation

POST /a/v1/organizations/{orgId}/invitations

Emails an invitation code to the invitee. The code is never returned by the API; it exists only in the email.

Who can call it: Signed-in user only: do this in the Yona app.

Parameters

Request body

Example request

curl -X POST https://gp.useyona.com/a/v1/organizations/me/invitations \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ada@acme.ng",
    "fullName": "Ada Obi"
  }'

Responses

Get an invitation

GET /a/v1/organizations/{orgId}/invitations/{id}

One invitation of the organisation, without its code.

Who can call it: Signed-in user only: do this in the Yona app.

Parameters

Example request

curl https://gp.useyona.com/a/v1/organizations/me/invitations/9f8e7d6c-5b4a-3210-fedc-ba9876543210 \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Responses

Withdraw a pending invitation

DELETE /a/v1/organizations/{orgId}/invitations/{id}

Who can call it: Signed-in user only: do this in the Yona app.

Parameters

Example request

curl -X DELETE https://gp.useyona.com/a/v1/organizations/me/invitations/9f8e7d6c-5b4a-3210-fedc-ba9876543210 \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Responses

Resend an invitation

POST /a/v1/organizations/{orgId}/invitations/{id}/resend

Emails the invitee a new code; the previous code stops working.

Who can call it: Signed-in user only: do this in the Yona app.

Parameters

Example request

curl -X POST https://gp.useyona.com/a/v1/organizations/me/invitations/9f8e7d6c-5b4a-3210-fedc-ba9876543210/resend \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Responses

Accept an invitation

POST /a/v1/accept-invitation

The signed-in user, whose verified email is the invitee’s, joins the organisation. No tokens are returned: to work in the new organisation, switch to it with POST /a/v1/organizations/switch.

Who can call it: Signed-in user only: do this in the Yona app.

Request body

Example request

curl -X POST https://gp.useyona.com/a/v1/accept-invitation \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "invitationCode": "K7M2Q9XA"
  }'

Responses

Preview an invitation

POST /a/v1/verify-invitation

Public. Given the invitation code and the invitee’s email, returns what the invitee may see before accepting. Any mismatch answers the same 404.

Who can call it: Signed-in user only: do this in the Yona app.

Request body

Example request

curl -X POST https://gp.useyona.com/a/v1/verify-invitation \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "invitationCode": "K7M2Q9XA",
    "email": "ada@example.com"
  }'

Responses