{ "openapi": "3.1.0", "info": { "title": "my-data.app Partner API", "version": "1.0.0", "summary": "Register merchants, check email ownership and read registration status with a scoped partner key.", "description": "Server-to-server API that lets a partner create my-data.app accounts for its own merchants. Requests are authenticated with a bearer partner key (mdp_production_<64 hex characters>). Keys are scoped, created and rotated in the my-data.app administrator console, shown once and revoked immediately on rotation. Each key is limited to 60 requests per minute and a 16384 byte JSON request body.", "x-legal-version": "2026-07-12" }, "servers": [ { "url": "https://my-data.app" } ], "security": [ { "partnerKey": [] } ], "tags": [ { "name": "Requirements" }, { "name": "Users" }, { "name": "Registrations" } ], "x-registration-statuses": [ "processing", "ready", "linking_required", "recoverable_failure" ], "x-registration-examples": { "password-ready": { "registration_id": "pr_00000000-0000-4000-8000-000000000000", "sign_in_url": "https://my-data.app/sign-in?lang=en", "status": "ready" }, "automatic-ready": { "registration_id": "pr_00000000-0000-4000-8000-000000000000", "sign_in_url": "https://my-data.app/sign-in?lang=en", "status": "ready", "automatic_sign_in_url": "https://my-data.app/connect/partner#ticket=EXAMPLE_TICKET", "expires_at": "2026-10-01T10:06:00Z" }, "linking_required": { "registration_id": "pr_00000000-0000-4000-8000-000000000000", "sign_in_url": "https://my-data.app/sign-in?lang=en", "status": "linking_required", "linking_url": "https://my-data.app/connect/partner#link=EXAMPLE_LINK", "expires_at": "2026-10-01T10:16:00Z" } }, "x-error-codes": [ "invalid_partner_key", "partner_scope_required", "partner_capability_required", "rate_limited", "invalid_json", "invalid_input", "payload_too_large", "legal_version_outdated", "idempotency_conflict", "registration_busy", "registration_not_found", "identity_conflict", "password_rejected", "identity_unavailable", "login_window_expired", "login_unavailable", "link_invalid", "link_email_mismatch", "auth_required", "invalid_origin", "method_not_allowed", "not_found", "partner_unavailable" ], "x-limits": { "bodyBytes": 16384, "requestsPerMinute": 60, "loginSeconds": 300, "loginWindowSeconds": 600, "linkSeconds": 900, "leaseSeconds": 120 }, "paths": { "/api/partners/v1/requirements": { "get": { "tags": [ "Requirements" ], "operationId": "getPartnerRequirements", "summary": "Read the current legal version, legal documents, scopes and limits", "description": "Read this before creating a registration. The returned legal_version is the version the merchant must accept.", "security": [ { "partnerKey": [] } ], "x-required-scopes": [ "requirements:read" ], "responses": { "200": { "description": "Current partner requirements", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Requirements" }, "example": { "legal_version": "2026-07-12", "legal_documents": { "terms": "https://my-data.app/terms", "privacy": "https://my-data.app/privacy", "data_processing_addendum": "https://my-data.app/data-processing-addendum" }, "scopes": [ "requirements:read", "users:check", "registrations:write", "registrations:read" ], "limits": { "bodyBytes": 16384, "requestsPerMinute": 60, "loginSeconds": 300, "loginWindowSeconds": 600, "linkSeconds": 900, "leaseSeconds": 120 } } } } }, "401": { "description": "Missing, unknown or revoked partner key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The partner key lacks the required scope, the partner capability is disabled, or HTTPS is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "Recognized endpoint called with an unsupported method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Per-key rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "retry-after": { "description": "Seconds to wait before retrying", "schema": { "type": "integer", "example": 60 } } } }, "503": { "description": "Identity or partner service unavailable; retry later with the same idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/partners/v1/users/check": { "post": { "tags": [ "Users" ], "operationId": "checkPartnerUser", "summary": "Check whether an email address already owns a my-data.app account", "description": "Read-only check used to choose between account creation and authenticated linking. It never creates or changes an account.", "security": [ { "partnerKey": [] } ], "x-required-scopes": [ "users:check" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 254 } } }, "example": { "email": "merchant@example.com" } } } }, "responses": { "200": { "description": "Whether the email address exists and any registration already created for it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserCheck" }, "example": { "exists": true, "registration": { "registration_id": "pr_00000000-0000-4000-8000-000000000000", "status": "ready" } } } } }, "400": { "description": "Malformed request, missing JSON object or invalid email", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, unknown or revoked partner key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The partner key lacks the required scope, the partner capability is disabled, or HTTPS is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "Recognized endpoint called with an unsupported method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Per-key rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "retry-after": { "description": "Seconds to wait before retrying", "schema": { "type": "integer", "example": 60 } } } }, "503": { "description": "Identity or partner service unavailable; retry later with the same idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/partners/v1/registrations": { "post": { "tags": [ "Registrations" ], "operationId": "createPartnerRegistration", "summary": "Create a merchant registration or an authenticated linking request", "description": "A new email address is provisioned in Clerk with the supplied password. Registration creates no workspace, trial, billing coverage or fiscal-provider connection; ordinary authenticated first use performs workspace and Test-trial provisioning. An existing email address requires authenticated linking consent through the returned linking_url and no password change.", "security": [ { "partnerKey": [] } ], "x-required-scopes": [ "registrations:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "example": "idem_example_7c4a1d" }, "description": "Partner-generated key. A replay with the same key returns the stored registration as 200 instead of creating a second one." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerRegistrationInput" }, "example": { "customer_id": "customer_123", "email": "merchant@example.com", "password": "EXAMPLE_PASSWORD_REPLACE_ME", "locale": "en", "login_mode": "password", "verified_email": { "verified_at": "2026-10-01T10:00:00Z", "reference": "verification_123" }, "legal_acceptance": { "version": "2026-07-12", "accepted_at": "2026-10-01T10:01:00Z", "reference": "consent_123" } } } } }, "responses": { "200": { "description": "Idempotent replay of an accepted registration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistrationResult" }, "examples": { "password_ready": { "summary": "New account with password sign-in", "value": { "registration_id": "pr_00000000-0000-4000-8000-000000000000", "sign_in_url": "https://my-data.app/sign-in?lang=en", "status": "ready" } }, "automatic_ready": { "summary": "New account with single-use automatic sign-in", "value": { "registration_id": "pr_00000000-0000-4000-8000-000000000000", "sign_in_url": "https://my-data.app/sign-in?lang=en", "status": "ready", "automatic_sign_in_url": "https://my-data.app/connect/partner#ticket=EXAMPLE_TICKET", "expires_at": "2026-10-01T10:06:00Z" } }, "linking_required": { "summary": "Existing email address requiring authenticated linking consent", "value": { "registration_id": "pr_00000000-0000-4000-8000-000000000000", "sign_in_url": "https://my-data.app/sign-in?lang=en", "status": "linking_required", "linking_url": "https://my-data.app/connect/partner#link=EXAMPLE_LINK", "expires_at": "2026-10-01T10:16:00Z" } } } } } }, "201": { "description": "Registration created. Exactly one of the mutually exclusive variants applies: password sign-in, automatic sign-in, or linking.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistrationResult" }, "examples": { "password_ready": { "summary": "New account with password sign-in", "value": { "registration_id": "pr_00000000-0000-4000-8000-000000000000", "sign_in_url": "https://my-data.app/sign-in?lang=en", "status": "ready" } }, "automatic_ready": { "summary": "New account with single-use automatic sign-in", "value": { "registration_id": "pr_00000000-0000-4000-8000-000000000000", "sign_in_url": "https://my-data.app/sign-in?lang=en", "status": "ready", "automatic_sign_in_url": "https://my-data.app/connect/partner#ticket=EXAMPLE_TICKET", "expires_at": "2026-10-01T10:06:00Z" } }, "linking_required": { "summary": "Existing email address requiring authenticated linking consent", "value": { "registration_id": "pr_00000000-0000-4000-8000-000000000000", "sign_in_url": "https://my-data.app/sign-in?lang=en", "status": "linking_required", "linking_url": "https://my-data.app/connect/partner#link=EXAMPLE_LINK", "expires_at": "2026-10-01T10:16:00Z" } } } } } }, "400": { "description": "Malformed request, missing JSON object, invalid input or invalid idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, unknown or revoked partner key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The partner key lacks the required scope, the partner capability is disabled, or HTTPS is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "Recognized endpoint called with an unsupported method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Idempotency conflict, registration busy, identity conflict or outdated legal version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "Request body above 16 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Identity provider rejected the password or account fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Per-key rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "retry-after": { "description": "Seconds to wait before retrying", "schema": { "type": "integer", "example": 60 } } } }, "503": { "description": "Identity or partner service unavailable; retry later with the same idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/partners/v1/registrations/{registration_id}": { "get": { "tags": [ "Registrations" ], "operationId": "getPartnerRegistration", "summary": "Read the status of a registration owned by this partner", "description": "Returns the registration identity, status and the normal sign-in URL. Linking and automatic sign-in URLs are never returned by this endpoint.", "security": [ { "partnerKey": [] } ], "x-required-scopes": [ "registrations:read" ], "parameters": [ { "name": "registration_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^pr_[a-f0-9-]{36}$", "example": "pr_00000000-0000-4000-8000-000000000000" } } ], "responses": { "200": { "description": "Registration status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistrationStatus" }, "example": { "registration_id": "pr_00000000-0000-4000-8000-000000000000", "status": "processing", "sign_in_url": "https://my-data.app/sign-in?lang=en" } } } }, "401": { "description": "Missing, unknown or revoked partner key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The partner key lacks the required scope, the partner capability is disabled, or HTTPS is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Unknown registration for this partner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "Recognized endpoint called with an unsupported method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Per-key rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "retry-after": { "description": "Seconds to wait before retrying", "schema": { "type": "integer", "example": 60 } } } }, "503": { "description": "Identity or partner service unavailable; retry later with the same idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } } }, "components": { "securitySchemes": { "partnerKey": { "type": "http", "scheme": "bearer", "bearerFormat": "mdp__<64 hex characters>", "description": "Partner API key created and rotated in the my-data.app administrator console. The key is shown once and revoked immediately on rotation. The scope each operation needs is documented in its x-required-scopes field." } }, "schemas": { "PartnerRegistrationInput": { "type": "object", "additionalProperties": false, "required": [ "customer_id", "email", "locale", "verified_email", "legal_acceptance" ], "properties": { "customer_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "email": { "type": "string", "format": "email", "maxLength": 254 }, "password": { "description": "Required only when creating a new account; omit for an existing account link or a completed registration replay.", "type": "string", "minLength": 8, "maxLength": 1024, "writeOnly": true }, "locale": { "type": "string", "enum": [ "el", "en" ] }, "first_name": { "type": "string", "maxLength": 100 }, "last_name": { "type": "string", "maxLength": 100 }, "login_mode": { "type": "string", "enum": [ "password", "automatic" ], "default": "password" }, "verified_email": { "type": "object", "additionalProperties": false, "required": [ "verified_at", "reference" ], "properties": { "verified_at": { "type": "string", "format": "date-time" }, "reference": { "type": "string", "minLength": 1, "maxLength": 128 } } }, "legal_acceptance": { "type": "object", "additionalProperties": false, "required": [ "version", "accepted_at", "reference" ], "properties": { "version": { "type": "string", "minLength": 1, "maxLength": 64 }, "accepted_at": { "type": "string", "format": "date-time" }, "reference": { "type": "string", "minLength": 1, "maxLength": 128 } } } }, "description": "Registration evidence for one merchant. Timestamps must not be more than 60 seconds in the future. The same email and password are used only when the email is new to my-data.app; an existing email is linked through consent and the password is not changed." }, "RegistrationResult": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "registration_id", "status", "sign_in_url" ], "properties": { "registration_id": { "type": "string" }, "sign_in_url": { "type": "string", "format": "uri", "description": "Normal sign-in URL for the merchant." }, "status": { "type": "string", "const": "ready" } } }, { "type": "object", "additionalProperties": false, "required": [ "registration_id", "status", "sign_in_url", "automatic_sign_in_url" ], "description": "New account with automatic login. The single-use token lasts five minutes.", "properties": { "registration_id": { "type": "string" }, "sign_in_url": { "type": "string", "format": "uri", "description": "Normal sign-in URL for the merchant." }, "status": { "type": "string", "const": "ready" }, "automatic_sign_in_url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } } }, { "type": "object", "additionalProperties": false, "required": [ "registration_id", "status", "sign_in_url", "linking_url" ], "description": "Existing email address. The merchant completes authenticated linking consent; the password is never changed.", "properties": { "registration_id": { "type": "string" }, "sign_in_url": { "type": "string", "format": "uri", "description": "Normal sign-in URL for the merchant." }, "status": { "type": "string", "const": "linking_required" }, "linking_url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } } }, { "type": "object", "additionalProperties": false, "required": [ "registration_id", "status", "sign_in_url" ], "description": "Work is still processing or recoverable; poll or retry with the same idempotency key.", "properties": { "registration_id": { "type": "string" }, "sign_in_url": { "type": "string", "format": "uri", "description": "Normal sign-in URL for the merchant." }, "status": { "type": "string", "enum": [ "processing", "recoverable_failure" ] } } } ] }, "RegistrationStatus": { "type": "object", "additionalProperties": false, "required": [ "registration_id", "status", "sign_in_url" ], "properties": { "registration_id": { "type": "string" }, "status": { "type": "string", "enum": [ "processing", "ready", "linking_required", "recoverable_failure" ] }, "sign_in_url": { "type": "string", "format": "uri" } } }, "UserCheck": { "type": "object", "additionalProperties": false, "required": [ "exists", "registration" ], "properties": { "exists": { "type": "boolean" }, "registration": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "registration_id", "status" ], "properties": { "registration_id": { "type": "string" }, "status": { "type": "string", "enum": [ "processing", "ready", "linking_required", "recoverable_failure" ] } } }, { "type": "null" } ] } } }, "Requirements": { "type": "object", "additionalProperties": false, "required": [ "legal_version", "legal_documents", "scopes", "limits" ], "properties": { "legal_version": { "type": "string", "example": "2026-07-12" }, "legal_documents": { "type": "object", "additionalProperties": false, "required": [ "terms", "privacy", "data_processing_addendum" ], "properties": { "terms": { "type": "string", "format": "uri" }, "privacy": { "type": "string", "format": "uri" }, "data_processing_addendum": { "type": "string", "format": "uri" } } }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "requirements:read", "users:check", "registrations:write", "registrations:read" ] } }, "limits": { "type": "object", "additionalProperties": false, "required": [ "bodyBytes", "requestsPerMinute", "loginSeconds", "loginWindowSeconds", "linkSeconds", "leaseSeconds" ], "properties": { "bodyBytes": { "type": "integer" }, "requestsPerMinute": { "type": "integer" }, "loginSeconds": { "type": "integer" }, "loginWindowSeconds": { "type": "integer" }, "linkSeconds": { "type": "integer" }, "leaseSeconds": { "type": "integer" } } } } }, "Problem": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_partner_key", "partner_scope_required", "partner_capability_required", "rate_limited", "invalid_json", "invalid_input", "payload_too_large", "legal_version_outdated", "idempotency_conflict", "registration_busy", "registration_not_found", "identity_conflict", "password_rejected", "identity_unavailable", "login_window_expired", "login_unavailable", "link_invalid", "link_email_mismatch", "auth_required", "invalid_origin", "method_not_allowed", "not_found", "partner_unavailable" ] }, "message": { "type": "string" } } } } } } } }