Documentation
Public API
List a team's 2FA accounts and fetch their TOTP codes from your own tools, with a dedicated token.
The API lets an authorised client list a team’s 2FA accounts and fetch their TOTP codes.
export API_URL="https://app.shareauth.net"
export API_TOKEN="1|your-sanctum-token"
Use HTTPS only in production. Requests and responses are JSON.
Authentication
Every call carries a Sanctum token in the header:
Authorization: Bearer 1|abcdefghijklmnopqrstuvwxyz
Accept: application/json
Create a token in the application
This is the recommended way. In your profile, under API tokens, choose the permissions and the validity period; you are asked for your password again, and the token is shown only once.
Create a token through the API
curl -X POST "$API_URL/api/tokens/create" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"email": "[email protected]",
"password": "password",
"device_name": "my-connector",
"abilities": ["secrets:list", "secrets:generate"],
"expires_in_days": 30,
"code": "123456"
}'
The second factor is mandatory, in one of these forms:
account protected by an authenticator app: the six-digit code in
code, or a recovery code inrecovery_code;account without an authenticator app: the first call, without
code, creates nothing. It answers409and sends a six-digit code by email:{ "message": "We emailed you a six-digit code. Send this request again with that code as confirmation_code.", "confirmation_required": true }Send the same request again with that code in
confirmation_code. It works only once and expires after 15 minutes.
Response:
{
"token": "1|abcdefghijklmnopqrstuvwxyz",
"abilities": ["secrets:list", "secrets:generate"],
"expires_at": "2026-11-18T10:00:00.000000Z",
"user": {
"id": 12,
"name": "Alice",
"email": "[email protected]"
}
}
Keep this token secret.
Permissions and validity
| Permission | Gives access to |
|---|---|
secrets:list | the list of 2FA accounts and the details of an account |
secrets:generate | the current code of an account |
teams:read | the teams, their members and switching the active team |
audit:read | the access log (team owner) |
integrations:manage | the messaging integrations (team owner) |
Without abilities, the token receives all five permissions: ask only for the
ones your tool needs. expires_in_days is 1, 7, 30 or 90, and 30 by default.
An account holds at most ten active tokens; expired tokens are removed
automatically, and the others can be revoked from the profile.
Creating, editing or deleting secrets and teams happens in the application: no token can be granted those rights.
Active team
The codes returned always belong to the user’s active team.
List the teams you can reach:
curl "$API_URL/api/v1/teams" \
-H "Authorization: Bearer $API_TOKEN" \
-H "Accept: application/json"
Switch the active team (teams:read permission):
curl -X POST "$API_URL/api/v1/teams/42/switch" \
-H "Authorization: Bearer $API_TOKEN" \
-H "Accept: application/json"
List 2FA accounts
curl "$API_URL/api/v1/secrets" \
-H "Authorization: Bearer $API_TOKEN" \
-H "Accept: application/json"
Shortened response:
{
"data": [
{
"id": 7,
"name": "GitHub production",
"issuer": "GitHub",
"digits": 6,
"period": 30
}
],
"meta": {
"total": 1,
"limit": 10,
"remaining": 9
}
}
The TOTP seed is never included in responses.
Fetch a code
Use the identifier returned by the list:
curl -X POST "$API_URL/api/v1/secrets/7/generate" \
-H "Authorization: Bearer $API_TOKEN" \
-H "Accept: application/json"
Response:
{
"data": {
"secret_name": "GitHub production",
"code": "123456",
"next_code": "654321",
"time_remaining": 18,
"period": 30,
"expires_at": "2026-08-13T12:00:30.000000Z"
}
}
Every generation is recorded in the team’s access log. Do not log the code on the client side.
Access log
Reserved for the owner of the active team, with a token carrying the audit:read permission. The log covers the website, the API and the messaging bots.
curl "$API_URL/api/v1/access-logs?channel=slack&limit=50" \
-H "Authorization: Bearer $API_TOKEN" \
-H "Accept: application/json"
Optional filters:
| Parameter | Values |
|---|---|
secret_id | identifier of one of the team’s secrets |
action | list, view or generate |
channel | web, api, slack, discord or teams |
limit | from 1 to 500, 100 by default |
Response:
{
"data": [
{
"id": 412,
"actor": {
"id": null,
"name": "sam",
"email": null,
"external_id": "U04ABCDEF",
"verified": false,
"deleted": false
},
"bot_integration_id": 3,
"secret": { "id": 7, "name": "GitHub production", "deleted": false },
"action": "generate",
"channel": "slack",
"ip_address": null,
"occurred_at": "2026-10-19T09:41:00.000000Z"
}
],
"meta": {
"total": 1,
"disclosures": 1,
"visible_since": "2026-07-21T00:00:00.000000Z",
"hidden": 0
}
}
actor.verifiedisfalsefor a bot: the name andexternal_idare those the platform reported, with no Share Auth account behind them.actor.deletedflags an account deleted since.meta.visible_sinceis the start of the period readable on the plan (7 days on Free, 90 on Team),nullon Business.meta.hiddencounts older entries, kept but hidden.
Errors
| Status | Meaning |
|---|---|
401 | token missing or invalid |
403 | access denied, or secret outside the active team |
404 | resource not found |
422 | invalid data, missing team, or code impossible to generate |
429 | rate limit of 60 requests per minute exceeded |
A validation error generally follows this shape:
{
"message": "The given data was invalid.",
"errors": {
"email": ["The email field is required."]
}
}
MCP connector
The MCP connector gives AI assistants (ChatGPT, Codex, Claude and other MCP clients) two tools: list the team’s 2FA accounts and get the current code. It never reads or returns the TOTP seed, and every code it obtains appears in the access log. It authenticates with a token limited to secrets:list and secrets:generate.
The connector is described in full on the AI agents (MCP) page. Its source code is public on GitHub, as is that of the 2FA skill for agents.