How-to guides

Manage members

Managing who can sign in to the //SCHEMA console for your organization. You need config_write — the owner or admin role.

Add a member#

Request

mutation {
  addOrgMember(input: { email: "[email protected]", displayName: "Kai", role: "member" }) {
    userPk
    role
    created
    password
  }
}

curl https://api.schema.fm/graphql \
  -H "Authorization: Bearer $SCHEMA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "query": "mutation {\n  addOrgMember(input: { email: \"[email protected]\", displayName: \"Kai\", role: \"member\" }) {\n    userPk\n    role\n    created\n    password\n  }\n}"
}
EOF

const res = await fetch("https://api.schema.fm/graphql", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SCHEMA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: `
      mutation {
        addOrgMember(input: { email: "[email protected]", displayName: "Kai", role: "member" }) {
          userPk
          role
          created
          password
        }
      }
    `,
  }),
});
const { data, errors } = await res.json();

Response

{
  "data": {
    "addOrgMember": {
      "userPk": 1052,
      "role": "member",
      "created": true,
      "password": "7KQ2M-D9XHT-4VRWB-P3NZE"
    }
  }
}

If created is true, a new account was made. Send the person their password securely; it is shown only now.
If created is false, the person already had a //SCHEMA account — they work with another organization too — and now also belongs to yours. They sign in with the password they already have, and password is null.

role defaults to member. Ask grantableRoles which roles you may give.

Roles#

Role	Can
`member`	Read and author the catalog, upload media. Cannot manage credentials or people.
`admin`	Everything, including keys, members and delivery accounts.
`owner`	Everything an admin can, and can make others owners.

Change a role#

Request

mutation {
  setOrgMemberRole(userPk: 1052, role: "admin")
}

curl https://api.schema.fm/graphql \
  -H "Authorization: Bearer $SCHEMA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "query": "mutation {\n  setOrgMemberRole(userPk: 1052, role: \"admin\")\n}"
}
EOF

const res = await fetch("https://api.schema.fm/graphql", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SCHEMA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: `
      mutation {
        setOrgMemberRole(userPk: 1052, role: "admin")
      }
    `,
  }),
});
const { data, errors } = await res.json();

You cannot change your own role, only an owner can grant owner, and the last owner cannot be demoted. Role changes take effect on the member's next request.

Reset a password#

Request

mutation {
  resetOrgMemberPassword(userPk: 1052)
}

curl https://api.schema.fm/graphql \
  -H "Authorization: Bearer $SCHEMA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "query": "mutation {\n  resetOrgMemberPassword(userPk: 1052)\n}"
}
EOF

const res = await fetch("https://api.schema.fm/graphql", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SCHEMA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: `
      mutation {
        resetOrgMemberPassword(userPk: 1052)
      }
    `,
  }),
});
const { data, errors } = await res.json();

Returns a new generated password and signs the member out everywhere. It is refused for members who also belong to another organization — their password is not yours to change — and for your own account.

Change your own password#

Signed-in users change their own password with changePassword, which needs the current one. Their other sessions are signed out.

Remove a member#

Request

mutation {
  removeOrgMember(userPk: 1052)
}

curl https://api.schema.fm/graphql \
  -H "Authorization: Bearer $SCHEMA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "query": "mutation {\n  removeOrgMember(userPk: 1052)\n}"
}
EOF

const res = await fetch("https://api.schema.fm/graphql", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SCHEMA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: `
      mutation {
        removeOrgMember(userPk: 1052)
      }
    `,
  }),
});
const { data, errors } = await res.json();

Access ends immediately. The person's //SCHEMA account is not deleted — they may belong to other organizations. You cannot remove yourself.

Webhooks for membership, and the emails owners get#

A webhook can tell your own systems when someone is added (member.added), removed (member.removed) or given a different role (member.role_changed) — to provision or deprovision them elsewhere. Each carries the person's address and role.

Owners also receive email about webhooks themselves: whenever an endpoint is created, or changed so that it receives more than before, every owner is told where it sends, what it receives and who made the change. If you don't recognize one, delete the endpoint and revoke the credential that created it.

Audit access#

orgMembers lists everyone with their role, status and last sign-in. isYou marks the caller's own row; sharedWithOtherOrgs marks people whose password you cannot reset.