HonkIO Auth

Organizations

The sign-in policy, organizations, memberships, roles and invitations.

Get the sign-in policy

GET/v1/auth-apps/:id/sign-in-policy

Permission: auth_apps: r

Who can sign up, and whether the app requires two-step verification.

Request
curl https://api.honkio.ca/v1/auth-apps/APP_ID/sign-in-policy \
  -H "Authorization: Bearer mk_test_YOUR_KEY"
Response · 200
{
  "sign_up_mode": "open",
  "sign_up_domains": [],
  "two_step_required": false
}

Update the sign-in policy

PATCH/v1/auth-apps/:id/sign-in-policy

Permission: auth_apps: m

Changes the fields you send. Requiring two-step needs Pro or Business.

Body

NameTypeDescription
sign_up_mode"open" | "invite_only" | "domains"Who can sign up. open by default.
sign_up_domainsstring[]The email domains allowed to sign up when the mode is domains.
two_step_requiredbooleanRequire two-step verification for every user. Pro and Business.
Request
curl -X PATCH https://api.honkio.ca/v1/auth-apps/APP_ID/sign-in-policy \
  -H "Authorization: Bearer mk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sign_up_mode": "domains",
    "sign_up_domains": [
      "acme.ca"
    ]
  }'
Response · 200
{
  "sign_up_mode": "domains",
  "sign_up_domains": [
    "acme.ca"
  ],
  "two_step_required": false
}

List organizations

GET/v1/auth-apps/:id/organizations

Permission: auth_organizations: r

The app’s organizations.

Query parameters

NameTypeDescription
limitintegerHow many to return per page.
cursorstringThe next_cursor of the previous page.
Request
curl https://api.honkio.ca/v1/auth-apps/APP_ID/organizations \
  -H "Authorization: Bearer mk_test_YOUR_KEY"
Response · 200
{
  "data": [
    {
      "id": "org_clxxxorgxxxxxxxxxxxxxxx",
      "name": "Northwind",
      "slug": "northwind",
      "created_at": "2026-11-02T15:04:05.000Z",
      "two_step_required": false,
      "updated_at": "2026-11-02T15:04:05.000Z",
      "member_count": 12
    }
  ],
  "next_cursor": null
}

Create an organization

POST/v1/auth-apps/:id/organizations

Permission: auth_organizations: w

Business plan. Sends organization.created.

Body

NameTypeDescription
namerequiredstringThe organization’s name, shown in the picker.
slugstringUnique in the app; tokens carry it as org_slug.
two_step_requiredbooleanRequire two-step verification to sign in to this organization.
Request
curl -X POST https://api.honkio.ca/v1/auth-apps/APP_ID/organizations \
  -H "Authorization: Bearer mk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Northwind",
    "slug": "northwind"
  }'
Response · 201
{
  "id": "org_clxxxorgxxxxxxxxxxxxxxx",
  "name": "Northwind",
  "slug": "northwind",
  "created_at": "2026-11-02T15:04:05.000Z",
  "two_step_required": false,
  "updated_at": "2026-11-02T15:04:05.000Z"
}

Get an organization

GET/v1/auth-apps/:id/organizations/:orgId

Permission: auth_organizations: r

One organization.

Request
curl https://api.honkio.ca/v1/auth-apps/APP_ID/organizations/ORG_ID \
  -H "Authorization: Bearer mk_test_YOUR_KEY"
Response · 200
{
  "id": "org_clxxxorgxxxxxxxxxxxxxxx",
  "name": "Northwind",
  "slug": "northwind",
  "created_at": "2026-11-02T15:04:05.000Z",
  "two_step_required": false,
  "updated_at": "2026-11-02T15:04:05.000Z"
}

Update an organization

PATCH/v1/auth-apps/:id/organizations/:orgId

Permission: auth_organizations: m

Changes the fields you send. Sends organization.updated.

Body

NameTypeDescription
namestringThe organization’s name, shown in the picker.
slugstringUnique in the app; tokens carry it as org_slug.
two_step_requiredbooleanRequire two-step verification to sign in to this organization.
Request
curl -X PATCH https://api.honkio.ca/v1/auth-apps/APP_ID/organizations/ORG_ID \
  -H "Authorization: Bearer mk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "two_step_required": true
  }'
Response · 200
{
  "id": "org_clxxxorgxxxxxxxxxxxxxxx",
  "name": "Northwind",
  "slug": "northwind",
  "created_at": "2026-11-02T15:04:05.000Z",
  "two_step_required": true,
  "updated_at": "2026-11-02T15:04:05.000Z"
}

Delete an organization

DELETE/v1/auth-apps/:id/organizations/:orgId

Permission: auth_organizations: d

Deletes the organization. Members’ next refresh in it fails. Sends organization.deleted.

Request
curl -X DELETE https://api.honkio.ca/v1/auth-apps/APP_ID/organizations/ORG_ID \
  -H "Authorization: Bearer mk_test_YOUR_KEY"

204 · No content.

List members

GET/v1/auth-apps/:id/organizations/:orgId/memberships

Permission: auth_organizations: r

The organization’s members and their roles. Each member’s name, email and phone (user) are included only when your key can also read users (auth_users read).

Query parameters

NameTypeDescription
limitintegerHow many to return per page.
cursorstringThe next_cursor of the previous page.
Request
curl https://api.honkio.ca/v1/auth-apps/APP_ID/organizations/ORG_ID/memberships \
  -H "Authorization: Bearer mk_test_YOUR_KEY"
Response · 200
{
  "data": [
    {
      "organization_id": "org_clxxxorgxxxxxxxxxxxxxxx",
      "user_id": "usr_clxxxuserxxxxxxxxxxxxxx",
      "role": "admin",
      "last_used_at": null,
      "created_at": "2026-11-02T15:04:05.000Z",
      "updated_at": "2026-11-02T15:04:05.000Z",
      "user": {
        "name": "Olivia Tremblay",
        "email": "olivia@northwind.ca",
        "phone": null
      }
    }
  ],
  "next_cursor": null
}

Add a member

POST/v1/auth-apps/:id/organizations/:orgId/memberships

Permission: auth_organizations: w

Adds an existing user with a role. Sends membership.created.

Body

NameTypeDescription
user_idrequiredstringThe user’s ID (usr_…).
rolestringadmin, member or one of your roles.
Request
curl -X POST https://api.honkio.ca/v1/auth-apps/APP_ID/organizations/ORG_ID/memberships \
  -H "Authorization: Bearer mk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_clxxxuserxxxxxxxxxxxxxx",
    "role": "admin"
  }'
Response · 201
{
  "organization_id": "org_clxxxorgxxxxxxxxxxxxxxx",
  "user_id": "usr_clxxxuserxxxxxxxxxxxxxx",
  "role": "admin",
  "last_used_at": null,
  "created_at": "2026-11-02T15:04:05.000Z",
  "updated_at": "2026-11-02T15:04:05.000Z"
}

Get a membership

GET/v1/auth-apps/:id/organizations/:orgId/memberships/:userId

Permission: auth_organizations: r

One user’s role in the organization.

Request
curl https://api.honkio.ca/v1/auth-apps/APP_ID/organizations/ORG_ID/memberships/USER_ID \
  -H "Authorization: Bearer mk_test_YOUR_KEY"
Response · 200
{
  "organization_id": "org_clxxxorgxxxxxxxxxxxxxxx",
  "user_id": "usr_clxxxuserxxxxxxxxxxxxxx",
  "role": "admin",
  "last_used_at": null,
  "created_at": "2026-11-02T15:04:05.000Z",
  "updated_at": "2026-11-02T15:04:05.000Z"
}

Change a member’s role

PATCH/v1/auth-apps/:id/organizations/:orgId/memberships/:userId

Permission: auth_organizations: m

Tokens carry the new role from the next refresh. Sends membership.updated.

Body

NameTypeDescription
rolerequiredstringadmin, member or one of your roles.
Request
curl -X PATCH https://api.honkio.ca/v1/auth-apps/APP_ID/organizations/ORG_ID/memberships/USER_ID \
  -H "Authorization: Bearer mk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "member"
  }'
Response · 200
{
  "organization_id": "org_clxxxorgxxxxxxxxxxxxxxx",
  "user_id": "usr_clxxxuserxxxxxxxxxxxxxx",
  "role": "member",
  "last_used_at": null,
  "created_at": "2026-11-02T15:04:05.000Z",
  "updated_at": "2026-11-02T15:04:05.000Z"
}

Remove a member

DELETE/v1/auth-apps/:id/organizations/:orgId/memberships/:userId

Permission: auth_organizations: d

Their next refresh in the organization fails with invalid_grant, within 10 minutes. Sends membership.deleted at once.

Request
curl -X DELETE https://api.honkio.ca/v1/auth-apps/APP_ID/organizations/ORG_ID/memberships/USER_ID \
  -H "Authorization: Bearer mk_test_YOUR_KEY"

204 · No content.

List roles

GET/v1/auth-apps/:id/organizations/:orgId/roles

Permission: auth_organizations: r

admin, member and your own roles. built_in is true for the first two, which can’t be deleted.

Request
curl https://api.honkio.ca/v1/auth-apps/APP_ID/organizations/ORG_ID/roles \
  -H "Authorization: Bearer mk_test_YOUR_KEY"
Response · 200
{
  "data": [
    {
      "name": "admin",
      "built_in": true,
      "two_step_required": false
    },
    {
      "name": "member",
      "built_in": true,
      "two_step_required": false
    },
    {
      "name": "billing",
      "built_in": false,
      "two_step_required": true
    }
  ]
}

Create or update a role

PUT/v1/auth-apps/:id/organizations/:orgId/roles/:name

Permission: auth_organizations: m

Adds the role to the organization, or changes its two-step requirement if it exists. The name is in the path.

Body

NameTypeDescription
two_step_requiredbooleanRequire two-step verification of members with this role.
Request
curl -X PUT https://api.honkio.ca/v1/auth-apps/APP_ID/organizations/ORG_ID/roles/ROLE_NAME \
  -H "Authorization: Bearer mk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "two_step_required": true
  }'
Response · 200
{
  "name": "billing",
  "built_in": false,
  "two_step_required": true
}

Delete a role

DELETE/v1/auth-apps/:id/organizations/:orgId/roles/:name

Permission: auth_organizations: d

Removes a role you created.

Request
curl -X DELETE https://api.honkio.ca/v1/auth-apps/APP_ID/organizations/ORG_ID/roles/ROLE_NAME \
  -H "Authorization: Bearer mk_test_YOUR_KEY"

204 · No content.

List invitations

GET/v1/auth-apps/:id/invitations

Permission: auth_organizations: r

Pending, accepted and revoked invitations.

Query parameters

NameTypeDescription
limitintegerHow many to return per page.
cursorstringThe next_cursor of the previous page.
Request
curl https://api.honkio.ca/v1/auth-apps/APP_ID/invitations \
  -H "Authorization: Bearer mk_test_YOUR_KEY"
Response · 200
{
  "data": [
    {
      "id": "inv_clxxxinvitexxxxxxxxxxxxx",
      "email": "grace@example.com",
      "phone": null,
      "organization_id": "org_clxxxorgxxxxxxxxxxxxxxx",
      "role": "member",
      "status": "pending",
      "redirect_url": null,
      "expires_at": "2026-11-09T15:04:05.000Z",
      "accepted_at": null,
      "accepted_user_id": null,
      "revoked_at": null,
      "created_at": "2026-11-02T15:04:05.000Z"
    }
  ],
  "next_cursor": null
}

Create an invitation

POST/v1/auth-apps/:id/invitations

Permission: auth_organizations: w

Sends an invitation by email or text. It works once, for 7 days, and only for the invited identifier.

Body

NameTypeDescription
emailstringThe email to invite. Send this or phone.
phonestringThe Canadian mobile number to invite, in E.164. Send this or email.
organization_idstringThe organization to join on acceptance.
rolestringThe role in that organization.
redirect_urlstringWhere to send the person after they accept. One of the app’s redirect URIs.
locale"en" | "fr"The language of the invitation email.
send_emailbooleanSend the invitation by email. Set it to false to share the returned link yourself.
Request
curl -X POST https://api.honkio.ca/v1/auth-apps/APP_ID/invitations \
  -H "Authorization: Bearer mk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "grace@example.com",
    "organization_id": "org_clxxxorgxxxxxxxxxxxxxxx",
    "role": "member"
  }'
Response · 201
{
  "id": "inv_clxxxinvitexxxxxxxxxxxxx",
  "email": "grace@example.com",
  "phone": null,
  "organization_id": "org_clxxxorgxxxxxxxxxxxxxxx",
  "role": "member",
  "status": "pending",
  "redirect_url": null,
  "expires_at": "2026-11-09T15:04:05.000Z",
  "accepted_at": null,
  "accepted_user_id": null,
  "revoked_at": null,
  "created_at": "2026-11-02T15:04:05.000Z",
  "url": "https://login-dev.acme.ca/invitations/xxxxxxxxxxxxxxxxxxxxxxxx"
}

Get an invitation

GET/v1/auth-apps/:id/invitations/:invitationId

Permission: auth_organizations: r

Its status: pending, accepted, revoked or expired.

Request
curl https://api.honkio.ca/v1/auth-apps/APP_ID/invitations/INVITATION_ID \
  -H "Authorization: Bearer mk_test_YOUR_KEY"
Response · 200
{
  "id": "inv_clxxxinvitexxxxxxxxxxxxx",
  "email": "grace@example.com",
  "phone": null,
  "organization_id": "org_clxxxorgxxxxxxxxxxxxxxx",
  "role": "member",
  "status": "pending",
  "redirect_url": null,
  "expires_at": "2026-11-09T15:04:05.000Z",
  "accepted_at": null,
  "accepted_user_id": null,
  "revoked_at": null,
  "created_at": "2026-11-02T15:04:05.000Z"
}

Revoke an invitation

DELETE/v1/auth-apps/:id/invitations/:invitationId

Permission: auth_organizations: d

The link stops working. Returns the revoked invitation.

Request
curl -X DELETE https://api.honkio.ca/v1/auth-apps/APP_ID/invitations/INVITATION_ID \
  -H "Authorization: Bearer mk_test_YOUR_KEY"
Response · 200
{
  "id": "inv_clxxxinvitexxxxxxxxxxxxx",
  "email": "grace@example.com",
  "phone": null,
  "organization_id": "org_clxxxorgxxxxxxxxxxxxxxx",
  "role": "member",
  "status": "revoked",
  "redirect_url": null,
  "expires_at": "2026-11-09T15:04:05.000Z",
  "accepted_at": null,
  "accepted_user_id": null,
  "revoked_at": "2026-11-03T10:00:00.000Z",
  "created_at": "2026-11-02T15:04:05.000Z"
}