{ "openapi": "3.1.0", "info": { "title": "Notif Auth", "version": "0.1.0", "description": "Private pilot. No outgoing WhatsApp messages. Usage conditions: /terms. Data processing: /privacy. Browser mutations require same Origin." }, "servers": [ { "url": "https://auth.notif.ml" }, { "url": "http://localhost:3100", "description": "Local sandbox" } ], "paths": { "/authorize": { "get": { "summary": "Create a 90-second login session", "security": [], "parameters": [ { "name": "client_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "redirect_uri", "in": "query", "required": true, "schema": { "type": "string", "format": "uri" } }, { "name": "state", "in": "query", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 256 } }, { "name": "response_type", "in": "query", "required": false, "schema": { "const": "code" } }, { "name": "code_challenge", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, { "name": "code_challenge_method", "in": "query", "required": false, "schema": { "const": "S256" } } ], "responses": { "303": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "PKCE S256 is mandatory for PUBLIC clients. Exact redirect allowlist; localhost port tolerance in TEST only. Returns a session cookie and redirects to static /waiting.html." } }, "/authorize/activate": { "post": { "summary": "Activate before opening WhatsApp", "security": [ { "sessionCookie": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "loginKeyId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } }, "required": [ "loginKeyId" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "activated": { "const": true }, "deeplink": { "type": [ "string", "null" ] } }, "required": [ "activated", "deeplink" ] } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/authorize/status": { "get": { "summary": "Poll every two seconds using the original session", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "loginKeyId", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/authorize/sandbox": { "post": { "summary": "Simulate an inbound message for TEST clients only", "security": [ { "sessionCookie": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "loginKeyId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "phoneE164": { "enum": [ "22300000001", "22300000002", "22300000003", "22300000004", "22300000005", "22300000006", "22300000007", "22300000008", "22300000009", "22300000099" ] } }, "required": [ "loginKeyId", "phoneE164" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "verified": { "const": true }, "duplicate": { "type": "boolean" } }, "required": [ "verified", "duplicate" ] } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/token": { "post": { "summary": "Exchange one code exactly once; validates client, redirect and PKCE", "security": [], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/TokenRequest" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/internal/verify": { "post": { "summary": "SMSV HMAC proof; loopback only, never publicly proxied", "security": [ { "smsvHmac": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Verify" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "verified": { "const": true }, "duplicate": { "type": "boolean" } }, "required": [ "verified", "duplicate" ] } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-internal": true } }, "/.well-known/jwks.json": { "get": { "summary": "Active and previous public RSA keys", "security": [], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "type": "object", "properties": { "kty": { "const": "RSA" }, "n": { "type": "string" }, "e": { "type": "string" }, "kid": { "type": "string" }, "alg": { "const": "RS256" }, "use": { "const": "sig" } }, "required": [ "kty", "n", "e", "kid", "alg", "use" ] } } }, "required": [ "keys" ] } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/.well-known/oauth-authorization-server": { "get": { "summary": "OAuth authorization server metadata", "security": [], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/healthz": { "get": { "summary": "PostgreSQL and Redis health", "security": [], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "enum": [ "ok", "unavailable" ] }, "service": { "const": "notif-auth" } }, "required": [ "status", "service" ] } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/manage/login": { "post": { "summary": "Redeem tenant invitation key for one-hour session", "security": [], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tenantId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "key": { "type": "string", "minLength": 32 } }, "required": [ "tenantId", "key" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/manage/logout": { "post": { "summary": "Revoke the current dashboard session", "security": [ { "dashboardCookie": [] } ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/manage/overview": { "get": { "summary": "Own clients and 50 most recent redacted events", "security": [ { "dashboardCookie": [] } ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "tenant": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "clients": { "type": "array", "items": { "$ref": "#/components/schemas/Client" } }, "events": { "type": "array", "items": { "type": "object" } } }, "required": [ "tenant", "clients", "events" ] } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/manage/clients": { "post": { "summary": "Create client; confidential secret shown once", "security": [ { "dashboardCookie": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientInput" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Client" }, { "type": "object", "properties": { "clientSecret": { "type": [ "string", "null" ] } }, "required": [ "clientSecret" ] } ] } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/manage/clients/{id}": { "patch": { "summary": "Update exact redirect allowlist and activation", "security": [ { "dashboardCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "redirectUris": { "type": "array", "items": { "type": "string", "format": "uri" } }, "active": { "type": "boolean" } }, "required": [ "redirectUris", "active" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Client" } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/manage/clients/{id}/rotate": { "post": { "summary": "Replace client secret immediately", "security": [ { "dashboardCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "clientSecret": { "type": "string" } }, "required": [ "clientSecret" ] } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "Error": { "type": "object", "properties": { "error": { "enum": [ "invalid_request", "invalid_client", "invalid_grant", "access_denied" ] }, "error_code": { "type": "string" }, "error_description": { "type": "string" }, "docs_url": { "type": "string", "format": "uri" }, "request_id": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } }, "required": [ "error", "error_code", "error_description", "docs_url", "request_id" ] }, "Profile": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "tenant_id": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "phone_e164": { "type": "string", "pattern": "^[1-9][0-9]{7,14}$" }, "display_name": { "type": [ "string", "null" ] }, "provider": { "enum": [ "whatsapp", "sandbox" ] }, "mode": { "enum": [ "LIVE", "TEST" ] }, "first_seen_at": { "type": "string", "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": true } }, "required": [ "id", "tenant_id", "phone_e164", "display_name", "provider", "mode", "first_seen_at", "metadata" ] }, "TokenRequest": { "type": "object", "properties": { "grant_type": { "const": "authorization_code", "default": "authorization_code" }, "code": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "client_id": { "type": "string" }, "client_secret": { "type": "string" }, "code_verifier": { "type": "string", "minLength": 43, "maxLength": 128 }, "redirect_uri": { "type": "string", "format": "uri" } }, "required": [ "code", "client_id", "redirect_uri" ] }, "TokenResponse": { "type": "object", "properties": { "token": { "type": "string" }, "access_token": { "type": "string" }, "token_type": { "const": "Bearer" }, "expires_in": { "const": 900 }, "subject": { "type": "string" }, "issued_at": { "type": "string", "format": "date-time" }, "profile": { "$ref": "#/components/schemas/Profile" } }, "required": [ "token", "access_token", "token_type", "expires_in", "subject", "issued_at", "profile" ] }, "Verify": { "type": "object", "properties": { "loginKeyId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "phoneE164": { "type": "string", "pattern": "^\\+?[1-9][0-9]{7,14}$" }, "displayName": { "type": "string", "maxLength": 100 }, "messageId": { "type": "string", "maxLength": 256 }, "timestamp": { "type": "integer", "description": "Unix time in milliseconds; maximum clock skew 60 seconds" }, "receiverPhoneId": { "type": "string" }, "matchingWords": { "type": "string" } }, "required": [ "loginKeyId", "phoneE164", "messageId", "timestamp", "receiverPhoneId", "matchingWords" ] }, "ClientInput": { "type": "object", "properties": { "type": { "enum": [ "PUBLIC", "CONFIDENTIAL" ] }, "mode": { "enum": [ "TEST", "LIVE" ] }, "redirectUris": { "type": "array", "items": { "type": "string", "format": "uri" }, "minItems": 1, "maxItems": 20 } }, "required": [ "type", "mode", "redirectUris" ] }, "Client": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "tenantId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "clientId": { "type": "string" }, "type": { "enum": [ "PUBLIC", "CONFIDENTIAL" ] }, "mode": { "enum": [ "TEST", "LIVE" ] }, "redirectUris": { "type": "array", "items": { "type": "string", "format": "uri" } }, "active": { "type": "boolean" } }, "required": [ "id", "tenantId", "clientId", "type", "mode", "redirectUris", "active" ] }, "Status": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "status": { "enum": [ "PENDING", "ACTIVATED", "VERIFIED", "CONSUMED", "EXPIRED" ] }, "mode": { "enum": [ "LIVE", "TEST" ] }, "matchingWords": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "serverTime": { "type": "string", "format": "date-time" }, "tenantName": { "type": "string" }, "redirectUrl": { "type": "string", "format": "uri" } }, "required": [ "id", "status", "mode", "matchingWords", "expiresAt", "serverTime", "tenantName" ] } }, "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "nauth_sid" }, "dashboardCookie": { "type": "apiKey", "in": "cookie", "name": "nauth_dashboard" }, "smsvHmac": { "type": "apiKey", "in": "header", "name": "X-SMSV-Signature", "description": "Hex HMAC-SHA256 of exact raw request body" } } } }