The Organizations API: Platform Saga Part III

In this chapter we'll learn about the Organization API that Turso provides you to manage all members of your organization, including adding, removing, and updating members.

Before you continue, make sure you've read the previous chapters in this series:

There are three core elements to the Organization API:

Organization: The top-level entity that represents your company.
Member: A member of your organization.
Invite: An invitation to join an organization.

Depending on whether you're inviting someone who is already a user of Turso will depend on the API you use to add them to your organization.

If they're already a user, you can use the Members API. If they're not a user, you can use the Invites API.

#Organizations

An organization is made up of the following properties:

name — The organization name.
slug — The organization slug.
type — The organization type (personal or team).
blocked_reads — Whether the organization is blocked from reading data.
blocked_writes — Whether the organization is blocked from writing data.
overages — Whether the organization is allowed to go over its limits.

A team account type allows you to add and invite other members. A personal account type is for individual use only.

Each API endpoint begins with the v1/organizations path. This is because all entities belong to an organization, including personal accounts.

#List all organizations

To retrieve a list of all the organizations you're a member of or own, you can make a request to GET /v1/organizations:

curl -L https://api.turso.tech/v1/organizations \
  -H 'Authorization: Bearer TOKEN'

This returns an array of objects containing the properties outlined above:

[
  {
    "blocked_reads": true,
    "blocked_writes": true,
    "name": "personal",
    "overages": false,
    "slug": "iku",
    "type": "personal"
  }
]

If you're a member of multiple organizations, you'll receive an array of objects, one for each organization.

#Update an organization

You can update your organization to enable or disable overages.

To do this, make a request to PATCH /v1/organizations/{organizationName} with a true or false value for the property overages:

curl -L -X PATCH https://api.turso.tech/v1/organizations/{organizationName} \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "overages": true
  }'

This returns the updated organization object that looks something like this:

{
  "organization": {
    "blocked_reads": true,
    "blocked_writes": true,
    "name": "personal",
    "overages": true,
    "slug": "iku",
    "type": "personal"
  }
}

#Members

The members API is used to manage all members of your organization, including adding, removing, and updating members.

An organization member is made up of the following properties:

email — The email address of the member.
role — The role of the member (owner, admin, or member).
username — The username of the member.

#List all members

To retrieve a list of all the members in your organization, you can make a request to GET /v1/organizations/{organizationName}/members:

curl -L https://api.turso.tech/v1/organizations/{organizationName}/members \
  -H 'Authorization: Bearer TOKEN'

This returns an array of objects containing the following properties:

{
  "members": [
    {
      "email": "iku@turso.tech",
      "role": "owner",
      "username": "iku"
    }
  ]
}

#Add a member

To add a member to your organization, you can make a request to POST /v1/organizations/{organizationName}/members with the selected role and the username. The member you're adding must already have a Turso account.

The role of the member you're adding can be admin or member. An admin can manage the organization and its members, while a member can only access the organization's resources.

curl --request POST \
  --url https://api.turso.tech/v1/organizations/{organizationName}/members \
  --header 'Content-Type: application/json' \
  --data '{
  "role": "member",
  "username": "<string>"
}'

This returns the member object that looks something like this:

{
  "member": "iku",
  "role": "member"
}

#Remove a member

To remove a member from your organization, you can make a request to DELETE /v1/organizations/{organizationName}/members/{username}:

curl -L -X DELETE https://api.turso.tech/v1/organizations/{organizationName}/members/{username} \
  -H 'Authorization: Bearer TOKEN'

This returns a 200 response that looks something like this:

{
  "member": "iku"
}

#Invites

The invites API is used by organization owners to invite new members to join their organization that aren't already a member of Turso.

An invite is made up of the following properties:

ID — The unique ID for the invite.
Email — The email address of the invitee.
Token — The unique token used to verify the invite.
Role — The role the invitee will have in the organization.
Accepted — The current status of the invite.
Organization — The organization the invite is for.
CreatedAt — The datetime the invite was created in ISO 8601 format. Example: 2024-01-01T00:00:00Z
DeletedAt — The datetime the invite was deleted (or revoked) in ISO 8601 format. Example: 2024-01-01T00:00:00Z
UpdatedAt — The datetime the invite was updated in ISO 8601 format. Example: 2024-01-01T00:00:00Z

#List all invites

To retrieve a list of all the invites in your organization, you can make a request to GET /v1/organizations/{organizationName}/invites:

curl --request POST \
  --url https://api.turso.tech/v1/organizations/{organizationName}/invites \
  --header 'Content-Type: application/json' \
  --data '{
  "role": "admin",
  "username": "<string>"
}'

This returns an array of objects containing the properties outlined above:

{
  "invited": {
    "Accepted": true,
    "CreatedAt": "2023-01-01T00:00:00Z",
    "DeletedAt": "2023-01-01T00:00:00Z",
    "Email": "iku@turso.tech",
    "ID": 1,
    "Organization": {
      "blocked_reads": true,
      "blocked_writes": true,
      "name": "personal",
      "overages": true,
      "slug": "iku",
      "type": "personal"
    },
    "OrganizationID": 1,
    "Role": "member",
    "Token": "3e393245b91b41ebad0980bc98349c9d",
    "UpdatedAt": "2023-01-01T00:00:00Z"
  }
}

#Create invite

You can invite someone who isn't already a Turso member to join Turso, and your organization by making a request to POST /v1/organizations/{organizationName}/invites:

curl -L https://api.turso.tech/v1/organizations/{organizationName}/invites \
  -H 'Authorization: Bearer TOKEN'

This returns an updated list of invites:

{
  "invites": [
    {
      "Accepted": true,
      "CreatedAt": "2023-01-01T00:00:00Z",
      "DeletedAt": "2023-01-01T00:00:00Z",
      "Email": "iku@turso.tech",
      "ID": 1,
      "Organization": {
        "blocked_reads": true,
        "blocked_writes": true,
        "name": "personal",
        "overages": true,
        "slug": "iku",
        "type": "personal"
      },
      "OrganizationID": 1,
      "Role": "member",
      "Token": "3e393245b91b41ebad0980bc98349c9d",
      "UpdatedAt": "2023-01-01T00:00:00Z"
    }
  ]
}

That's it! We now know the basics of the Organization API. We can list all organizations we're a member of, update an organization, list all members, add a member, remove a member, list all invites, and create an invite.

If you're building with the Turso API and want to programmatically manage how your organization is structured, the Organization API is what you'll want to use to do that.

#Going beyond the Organizations API

In the next chapter we will learn about retrieving a list of locations where databases can be created, and replicated to.

Go to next chapter