Organization Endpoints

Overview

Organizations are the primary way to group users and resources in Ryva. These endpoints allow you to create, update, and manage organizations.

All organization endpoints require JWT authentication.

Create Organization

POST

endpoint

/v1/organizations

Create a new organization. The authenticated user becomes the owner.

Request Body

name

string

required

Organization name (3-100 characters)

plan

string

required

Subscription plan: free, personal, or team

Response

string

required

Organization’s unique identifier (UUID)

name

string

required

Organization name

slug

string

URL-friendly slug (auto-generated for paid plans)

plan

string

required

Subscription plan

role

string

required

Your role in the organization (always owner for creator)

created_at

string

required

Timestamp when organization was created

Example

curl -X POST https://api.ryva.com/v1/organizations \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation",
    "plan": "team"
  }'

List Organizations

GET

endpoint

/v1/organizations

List all organizations the authenticated user belongs to.

Response

Returns an array of organization objects.

string

required

Organization’s unique identifier

name

string

required

Organization name

slug

string

URL-friendly slug

plan

string

required

Subscription plan: free, personal, or team

settings

object

required

Organization settings stored as key-value pairs

created_at

string

required

Creation timestamp

updated_at

string

required

Last update timestamp

Example

curl https://api.ryva.com/v1/organizations \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Get Organization

GET

endpoint

/v1/organizations/:id

Retrieve details of a specific organization.

Path Parameters

string

required

Organization ID (UUID)

Response

string

required

Organization’s unique identifier

name

string

required

Organization name

slug

string

URL-friendly slug

plan

string

required

Subscription plan

settings

object

required

Organization settings

created_at

string

required

Creation timestamp

updated_at

string

required

Last update timestamp

Example

curl https://api.ryva.com/v1/organizations/org-123e4567 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Update Organization

PATCH

endpoint

/v1/organizations/:id

Update an organization’s details. Requires owner or admin role.

Path Parameters

string

required

Organization ID (UUID)

Request Body

name

string

Organization name (3-100 characters)

plan

string

Subscription plan: free, personal, or team

settings

object

Organization settings as key-value pairs

The slug field is auto-generated and cannot be updated after creation.

Response

Returns the updated organization object.

Example

curl -X PATCH https://api.ryva.com/v1/organizations/org-123e4567 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp (Updated)",
    "settings": {
      "allow_public_signup": true
    }
  }'

Delete Organization

DELETE

endpoint

/v1/organizations/:id

Delete an organization. Only the owner can delete an organization.

This action is irreversible and will delete all associated data.

Path Parameters

string

required

Organization ID (UUID)

Response

Returns 204 No Content on success.

Example

curl -X DELETE https://api.ryva.com/v1/organizations/org-123e4567 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Invite Member

POST

endpoint

/v1/organizations/:id/invitations

Invite a user to join the organization. Requires owner or admin role.

Path Parameters

string

required

Organization ID (UUID)

Request Body

string

required

Email address of the person to invite

role

string

required

Role to assign: owner, admin, or member

Response

invitation_id

string

required

Invitation’s unique identifier

string

required

Email address that was invited

role

string

required

Role assigned in the invitation

expires_at

string

required

When the invitation expires

Example

curl -X POST https://api.ryva.com/v1/organizations/org-123e4567/invitations \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "colleague@example.com",
    "role": "member"
  }'

List Pending Invitations

GET

endpoint

/v1/organizations/:id/invitations

List all pending invitations for an organization.

Path Parameters

string

required

Organization ID (UUID)

Response

invitations

array

required

List of pending invitations

Show Invitation Object

invitation_id

string

required

Invitation’s unique identifier

string

required

Invited email address

role

string

required

Role assigned

invited_by

string

required

User ID who sent the invitation

invited_by_name

string

Name of the user who sent the invitation

sent_at

string

required

When invitation was sent

expires_at

string

required

When invitation expires

total

integer

required

Total number of pending invitations

Example

curl https://api.ryva.com/v1/organizations/org-123e4567/invitations \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Cancel Invitation

DELETE

endpoint

/v1/organizations/:id/invitations/:invitationId

Cancel a pending invitation.

Path Parameters

string

required

Organization ID (UUID)

invitationId

string

required

Invitation ID (UUID)

Response

Returns 204 No Content on success.

Example

curl -X DELETE https://api.ryva.com/v1/organizations/org-123/invitations/inv-456 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Resend Invitation

POST

endpoint

/v1/organizations/:id/invitations/:invitationId/resend

Resend an invitation email. Creates a new invitation with a fresh expiration.

Path Parameters

string

required

Organization ID (UUID)

invitationId

string

required

Invitation ID (UUID)

Response

Returns a new invitation object with updated expiration.

Example

curl -X POST https://api.ryva.com/v1/organizations/org-123/invitations/inv-456/resend \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Error Responses

Not Found (404)

{
  "error": {
    "message": "Organization not found",
    "code": "NOT_FOUND",
    "status": 404
  }
}

Forbidden (403)

{
  "error": {
    "message": "You don't have permission to access this organization",
    "code": "FORBIDDEN",
    "status": 403
  }
}

Validation Error (400)

{
  "error": {
    "message": "Invalid organization name",
    "code": "VALIDATION_ERROR",
    "status": 400
  }
}

Documentation Index

​Overview

​Create Organization

​Request Body

​Response

​Example

​List Organizations

​Response

​Example

​Get Organization

​Path Parameters

​Response

​Example

​Update Organization

​Path Parameters

​Request Body

​Response

​Example

​Delete Organization

​Path Parameters

​Response

​Example

​Invite Member

​Path Parameters

​Request Body

​Response

​Example

​List Pending Invitations

​Path Parameters

​Response

​Example

​Cancel Invitation

​Path Parameters

​Response

​Example

​Resend Invitation

​Path Parameters

​Response

​Example

​Error Responses

​Not Found (404)

​Forbidden (403)

​Validation Error (400)

Overview

Create Organization

Request Body

Response

Example

List Organizations

Response

Example

Get Organization

Path Parameters

Response

Example

Update Organization

Path Parameters

Request Body

Response

Example

Delete Organization

Path Parameters

Response

Example

Invite Member

Path Parameters

Request Body

Response

Example

List Pending Invitations

Path Parameters

Response

Example

Cancel Invitation

Path Parameters

Response

Example

Resend Invitation

Path Parameters

Response

Example

Error Responses

Not Found (404)

Forbidden (403)

Validation Error (400)