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.
curl https://api.honkio.ca/v1/auth-apps/APP_ID/sign-in-policy \
-H "Authorization: Bearer mk_test_YOUR_KEY"{
"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
| Name | Type | Description |
|---|---|---|
| sign_up_mode | "open" | "invite_only" | "domains" | Who can sign up. open by default. |
| sign_up_domains | string[] | The email domains allowed to sign up when the mode is domains. |
| two_step_required | boolean | Require two-step verification for every user. Pro and Business. |
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"
]
}'{
"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
| Name | Type | Description |
|---|---|---|
| limit | integer | How many to return per page. |
| cursor | string | The next_cursor of the previous page. |
curl https://api.honkio.ca/v1/auth-apps/APP_ID/organizations \
-H "Authorization: Bearer mk_test_YOUR_KEY"{
"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
| Name | Type | Description |
|---|---|---|
| namerequired | string | The organization’s name, shown in the picker. |
| slug | string | Unique in the app; tokens carry it as org_slug. |
| two_step_required | boolean | Require two-step verification to sign in to this organization. |
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"
}'{
"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.
curl https://api.honkio.ca/v1/auth-apps/APP_ID/organizations/ORG_ID \
-H "Authorization: Bearer mk_test_YOUR_KEY"{
"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
| Name | Type | Description |
|---|---|---|
| name | string | The organization’s name, shown in the picker. |
| slug | string | Unique in the app; tokens carry it as org_slug. |
| two_step_required | boolean | Require two-step verification to sign in to this organization. |
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
}'{
"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.
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
| Name | Type | Description |
|---|---|---|
| limit | integer | How many to return per page. |
| cursor | string | The next_cursor of the previous page. |
curl https://api.honkio.ca/v1/auth-apps/APP_ID/organizations/ORG_ID/memberships \
-H "Authorization: Bearer mk_test_YOUR_KEY"{
"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
| Name | Type | Description |
|---|---|---|
| user_idrequired | string | The user’s ID (usr_…). |
| role | string | admin, member or one of your roles. |
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"
}'{
"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.
curl https://api.honkio.ca/v1/auth-apps/APP_ID/organizations/ORG_ID/memberships/USER_ID \
-H "Authorization: Bearer mk_test_YOUR_KEY"{
"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
| Name | Type | Description |
|---|---|---|
| rolerequired | string | admin, member or one of your roles. |
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"
}'{
"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.
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.
curl https://api.honkio.ca/v1/auth-apps/APP_ID/organizations/ORG_ID/roles \
-H "Authorization: Bearer mk_test_YOUR_KEY"{
"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
| Name | Type | Description |
|---|---|---|
| two_step_required | boolean | Require two-step verification of members with this role. |
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
}'{
"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.
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
| Name | Type | Description |
|---|---|---|
| limit | integer | How many to return per page. |
| cursor | string | The next_cursor of the previous page. |
curl https://api.honkio.ca/v1/auth-apps/APP_ID/invitations \
-H "Authorization: Bearer mk_test_YOUR_KEY"{
"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
| Name | Type | Description |
|---|---|---|
| string | The email to invite. Send this or phone. | |
| phone | string | The Canadian mobile number to invite, in E.164. Send this or email. |
| organization_id | string | The organization to join on acceptance. |
| role | string | The role in that organization. |
| redirect_url | string | Where to send the person after they accept. One of the app’s redirect URIs. |
| locale | "en" | "fr" | The language of the invitation email. |
| send_email | boolean | Send the invitation by email. Set it to false to share the returned link yourself. |
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"
}'{
"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.
curl https://api.honkio.ca/v1/auth-apps/APP_ID/invitations/INVITATION_ID \
-H "Authorization: Bearer mk_test_YOUR_KEY"{
"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.
curl -X DELETE https://api.honkio.ca/v1/auth-apps/APP_ID/invitations/INVITATION_ID \
-H "Authorization: Bearer mk_test_YOUR_KEY"{
"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"
}
HonkIO