Introducing organisations

Why organisations?

This release of Span introduces organisations. It’s not a major change to the core API but it’s quite useful in a few key areas.

• The top level is organisation. You can be a member of several organisations.
• Each organisation can have zero or more teams.
• API tokens are no longer owned by users but by teams, in other words the API tokens are not assigned to a person but an organisations.

Why the changes to API tokens?

API tokens as they were was nice when prototyping but not so nice when you wanted to transition into a production setting. Any kind of personal credentials in a production environment is a cause for concern when someone changes team, quits or is unavailable.

Another nice side effect is that you can move entire setups from one organisation to a new one, for instance when a project transitions from development to production. Since both the API tokens and the collections are owned by the team any integrations you’ve written will continue to operate with the same API tokens without the need to change access credentials.

The downside to this is that the current version of the Span CLI will only show you the collections and devices for a single team but we’ve added a “login” command to the Span CLI to log in as a regular user.

Converting old api tokens and teams

The conversion is relatively simple but includes a bit of guesswork. The conversion is as follows:

• A new personal organisation is created for everyone. This replaces the old private team
• All other teams are converted to a new organisation with a single team. The memberships from the teams are preserved.
• API tokens involve a bit of guesswork but if the resource field is set to a collection it is moved to the same team as the collection. If the resource flag is set to “/” (ie everything) the token is moved to your private team.

Front end changes

There are some changes in the front end and the biggest you’ll notice is the new top menu. The “Teams” and “API tokens” menu items are moved into a new menu named “Organisations”

Organisations

The “organisations” section is used to manage your organisations and memberships. Initially you’ll only be a member of a single (personal) organisation. The personal organisation is an organisation where you are the only member.

The “Members” page is quite similar to the old team member page; enter email addresses to invite others to the organisation. The rules for the memberships are the same as for the old teams:

• You can’t change your own membership role
• Owners can change roles and invite members
• Regular members can only read

Teams

The new team page has changed a bit; members are selected from the organisation and are added as is. A team member can be the team owner (with write permissions on the team’s resources) without being an organisation owner. Organisation owners can modify the team meberships including their own role within a team.

API Tokens

Finally, the API token page shows all the API tokens for the teams in the organisation:

The API token editor has finally gotten a much needed quick select for the resource field.

Start page

Rather than showing the list of collections we’ve added a start page that shows you the three most recent collections, a list of organisations and teams you are a member of and any pending invites:

As always the API documentation is at https://span.lab5e.com/span/docs/ and the orgs, teams, tokens and user API documentation is available at https://span.lab5e.com/dejavu/docs/

If you want to generate your own OpenAPI client specss are available at http://span.lab5e.com/span/docs/api.json and http://span.lab5e.com/dejavu/docs/api.json.