Breadcrumbs

Administration

Every account in Circularo belongs to an organization, and the organization is what this chapter is about: the people in it, what each of them is allowed to do, and the record of what they did. Integrations reach for it when accounts should follow the systems you already run — a new hire in your HR system becoming a Circularo member, a leaver losing access the same day, a compliance system collecting the history without anyone exporting it by hand.

The organization and its people

  • Organization — the boundary around everything else. Every member belongs to exactly one, and every call you make here works inside yours; other organizations on the same instance are invisible.

  • Member — one person's account. It carries an identifier, a profile, a status (newly_created while an invitation is pending, active, suspended) and exactly one role.

  • Role — what a member may do: admin for someone who administers the organization, member for a regular colleague with full document and signing access, and the lighter signer, preparer and reader for people who only do one of those things. Which roles exist is part of how your organization was set up.

  • Group — an extra bundle of access on top of the role: permissions, and shared content its members can reach. A member can be in any number of groups.

  • Audit log — the organization-wide record of actions, written as they happen and only ever read back.

Membership works in one direction worth remembering: a role is set on the member, while a group is a thing a member is put into. Both end up in the member's groupIds, but you change them through different endpoints, and the API refuses attempts to change a role by moving people between groups.

How it typically goes

  1. A person joins, and you create the member — the role decides what they can do from the first minute.

  2. You put them into the groups their work needs, which opens up shared content.

  3. Their standing changes; you update the role or the status rather than making a second account.

  4. They leave, and you delete the member, handing their documents to somebody who stays.

  5. All of it lands in the audit log, which is where you go when somebody asks what happened.

Worth knowing across the chapter

  • An organization administrator does the work. Reading members and reading audit logs need only the corresponding permission, but creating, changing and deleting members, and everything to do with groups, requires an administrator's key. A key belonging to an instance-wide administrator is not a substitute — it is refused with 403. Issue integrator keys to an organization administrator; Authenticate and manage API keys covers how keys are created.

  • Identifiers are what you keep. A member is addressed by the id the API returned, not by the email address you sent.

  • Nothing reaches outside your organization, which is also why the members list, the group list and the audit log never need a scope parameter.

Where to start

Read Provision and manage members first: creating, updating and removing members is the bulk of what an administrative integration does, and it introduces roles and statuses. Manage group membership then adds the access a role alone does not give, and Search the audit logs is the read-only end — the one page in this chapter you may want even if you never provision anybody.