Platform foundations — service-account authorization (HTTP Basic client credentials exchanged for a bearer JWT), buyer login and token refresh, org-token exchange, one-time verification codes, org codes, and the common models shared across every other domain. 15 operations.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/foundations-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
{
"openapi": "3.0.3",
"info": {
"title": "Foundations",
"description": "Foundational platform capabilities like authentication as well as definitions of common models used across the platform",
"version": "2.0.0",
"contact": {
"email": "partnership-growth@getbread.com"
}
},
"servers": [
{
"url": "https://api-preview.platform.breadpayments.com/",
"description": "Preview environment"
},
{
"url": "https://api.platform.breadpayments.com/",
"description": "Production environment"
}
],
"paths": {
"/api/auth/send-code": {
"post": {
"tags": [
"Auth"
],
"summary": "Send a Verification OTP Code",
"description": "Sends a verification code to a Buyer's phone or email.",
"operationId": "sendCode",
"parameters": [
{
"name": "X-Bread-APP-ID",
"description": "The header containing a valid appID.",
"in": "header",
"schema": {
"type": "string"
},
"required": true
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"email",
"deliveryMethod",
"disclosures"
],
"type": "object",
"properties": {
"phone": {
"type": "string",
"description": "Telephone number including country code",
"example": "+14539842345"
},
"email": {
"type": "string",
"format": "email",
"description": "Email address",
"example": "john.doe@gmail.com"
},
"languagePreference": {
"type": "string",
"description": "The two language code as defined in ISO 639-1 along with subtags tag if applicable.",
"minLength": 2,
"example": "en or en-US",
"externalDocs": {
"description": "ISO 639-1",
"url": "https://en.wikipedia.org/wiki/ISO_639-1"
}
},
"deliveryMethod": {
"type": "string",
"description": "List of types of delivery methods.",
"enum": [
"SMS",
"EMAIL"
]
},
"disclosures": {
"description": "Disclosures is the list of disclosures to which a buyer provides consent.",
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"description": "A required disclosure.",
"type": "string"
},
"acceptedAt": {
"type": "string",
"format": "date-time",
"description": "The timestamp value formatted per RFC3339. This does not allow nulls.",
"example": "2020-12-31T15:10:55Z",
"externalDocs": {
"description": "RFC3339",
"url": "https://datatracker.ietf.org/doc/html/rfc3339#section-5.6"
}
}
}
}
},
"uat": {
"description": "The 'uat' object is optional. It gives UAT instructions to the service, so that users can mimic certain test scenarios. It is primarily used for setting a fixed OTP token instead of using one that is randomly generated. The 'uat' object has no effect on production environments.",
"type": "object",
"properties": {
"auth": {
"type": "object",
"properties": {
"token": {
"description": "The OTP code.",
"type": "string",
"example": "1234"
},
"phoneType": {
"description": "Type of phone",
"type": "string"
}
}
}
}
}
}
},
"examples": {
"rbcSMS": {
"summary": "RBC request with SMS OTP delivery",
"value": {
"phone": "+15555555555",
"email": "example@getbread.com",
"deliveryMethod": "SMS",
"languagePreference": "en-ca",
"disclosures": [
{
"type": "SMS",
"acceptedAt": "2020-12-31T15:10:55Z"
}
]
}
},
"rbcEmail": {
"summary": "RBC request with Email OTP delivery",
"value": {
"phone": "+15555555555",
"email": "example@getbread.com",
"deliveryMethod": "EMAIL",
"languagePreference": "en-ca",
"disclosures": [
{
"type": "Email",
"acceptedAt": "2020-12-31T15:10:55Z"
}
]
}
},
"ads": {
"summary": "ADS request with optional uat parameter",
"value": {
"phone": "+15555555555",
"email": "example@getbread.com",
"deliveryMethod": "SMS",
"languagePreference": "en-us",
"disclosures": [
{
"type": "terms-of-use",
"acceptedAt": "2021-01-21T21:01:35Z"
},
{
"type": "privacy-policy-choices",
"acceptedAt": "2021-08-26T21:01:35Z"
}
],
"uat": {
"auth": {
"token": "1234"
}
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "A response from a successful request to `POST /api/auth/send-code`.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "A response containing a JWT successfully returned from the `POST /api/auth/buyer/authorize` endpoint",
"required": [
"referenceID"
],
"properties": {
"referenceID": {
"description": "A identifier referencing an OTP code.",
"type": "string",
"format": "uuid"
}
}
}
}
}
},
"400": {
"description": "Response for Auth errors",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Default error model for Auth errors",
"allOf": [
{
"required": [
"code",
"domain",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "The underlying http status code",
"format": "int32",
"example": 500
},
"message": {
"type": "string",
"description": "A simple message in english describing the error and can be returned to the consumer",
"example": "Age cannot be less than 18"
},
"domain": {
"type": "string",
"description": "The domain where the error is originating from as defined by the service",
"example": "Payments"
},
"metadata": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Any additional details to be conveyed as determined by the service. If present, will return map of key value pairs",
"example": {
"propertyName": "propertyName is required"
}
}
}
}
],
"properties": {
"reason": {
"type": "string",
"description": "Auth error reason codes",
"default": "Request_Validation",
"enum": [
"Request_Validation",
"Not_Found",
"Unauthenticated",
"Unauthenticated_Retry_With_PII",
"Unauthenticated_Buyer_Mismatch",
"Unauthenticated_Buyer_Not_Found",
"Invalid_Token",
"Too_Many_Code_Attempts",
"Too_Many_Unverified_Codes_Sent",
"Dependency_Unavailable",
"System_Failure",
"Service_Unavailable"
],
"example": "Request_Validation"
}
}
},
"example": {
"code": 400,
"message": "Error(s) in payload",
"domain": "Auth",
"metadata": {
"email": "required"
},
"reason": "Request_Validation"
}
}
}
},
"401": {
"description": "Unauthorized. Indicates that provided credentials is not valid",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "Jwt is expired"
}
},
"application/json": {
"schema": {
"allOf": [
{
"required": [
"code",
"domain",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "The underlying http status code",
"format": "int32",
"example": 500
},
"message": {
"type": "string",
"description": "A simple message in english describing the error and can be returned to the consumer",
"example": "Age cannot be less than 18"
},
"domain": {
"type": "string",
"description": "The domain where the error is originating from as defined by the service",
"example": "Payments"
},
"metadata": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Any additional details to be conveyed as determined by the service. If present, will return map of key value pairs",
"example": {
"propertyName": "propertyName is required"
}
}
}
}
],
"required": [
"code",
"domain",
"message",
"reason"
],
"type": "object",
"properties": {
"reason": {
"type": "string",
"description": "A reason code specific to the service and can be used to identify the exact issue. Should be unique within a domain",
"example": "Reason_Code"
}
}
},
"example": {
"code": 401,
"domain": "Auth",
"message": "Invalid authentication",
"reason": "Invalid_Authentication"
}
}
}
},
"403": {
"description": "Forbidden. Indicates that request cannot be authorized",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "RBAC: Access Denied"
}
},
"application/json": {
"schema": {
"allOf": [
{
"required": [
"code",
"domain",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "The underlying http status code",
"format": "int32",
"example": 500
},
"message": {
"type": "string",
"description": "A simple message in english describing the error and can be returned to the consumer",
"example": "Age cannot be less than 18"
},
"domain": {
"type": "string",
"description": "The domain where the error is originating from as defined by the service",
"example": "Payments"
},
"metadata": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Any additional details to be conveyed as determined by the service. If present, will return map of key value pairs",
"example": {
"propertyName": "propertyName is required"
}
}
}
}
],
"required": [
"code",
"domain",
"message",
"reason"
],
"type": "object",
"properties": {
"reason": {
"type": "string",
"description": "A reason code specific to the service and can be used to identify the exact issue. Should be unique within a domain",
"example": "Reason_Code"
}
}
},
"example": {
"code": 403,
"domain": "Auth",
"message": "RBAC: Access Denied",
"reason": "Access_Denied"
}
}
}
},
"404": {
"description": "Buyer Not Found",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Default error model for Auth errors",
"allOf": [
{
"required": [
"code",
"domain",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "The underlying http status code",
"format": "int32",
"example": 500
},
"message": {
"type": "string",
"description": "A simple message in english describing the error and can be returned to the consumer",
"example": "Age cannot be less than 18"
},
"domain": {
"type": "string",
"description": "The domain where the error is originating from as defined by the service",
"example": "Payments"
},
"metadata": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Any additional details to be conveyed as determined by the service. If present, will return map of key value pairs",
"example": {
"propertyName": "propertyName is required"
}
}
}
}
],
"properties": {
"reason": {
"type": "string",
"description": "Auth error reason codes",
"default": "Request_Validation",
"enum": [
"Request_Validation",
"Not_Found",
"Unauthenticated",
"Unauthenticated_Retry_With_PII",
"Unauthenticated_Buyer_Mismatch",
"Unauthenticated_Buyer_Not_Found",
"Invalid_Token",
"Too_Many_Code_Attempts",
"Too_Many_Unverified_Codes_Sent",
"Dependency_Unavailable",
"System_Failure",
"Service_Unavailable"
],
"example": "Request_Validation"
}
}
},
"example": {
"code": 404,
"domain": "Auth",
"message": "Buyer Not Found",
"reason": "Not_Found"
}
}
}
},
"409": {
"description": "Buyer Conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Default error model for Auth errors",
"allOf": [
{
"required": [
"code",
"domain",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "The underlying http status code",
"format": "int32",
"example": 500
},
"message": {
"type": "string",
"description": "A simple message in english describing the error and can be returned to the consumer",
"example": "Age cannot be less than 18"
},
"domain": {
"type": "string",
"description": "The domain where the error is originating from as defined by the service",
"example": "Payments"
},
"metadata": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Any additional details to be conveyed as determined by the service. If present, will return map of key value pairs",
"example": {
"propertyName": "propertyName is required"
}
}
}
}
],
"properties": {
"reason": {
"type": "string",
"description": "Auth error reason codes",
"default": "Request_Validation",
"enum": [
"Request_Validation",
"Not_Found",
"Unauthenticated",
"Unauthenticated_Retry_With_PII",
"Unauthenticated_Buyer_Mismatch",
"Unauthenticated_Buyer_Not_Found",
"Invalid_Token",
"Too_Many_Code_Attempts",
"Too_Many_Unverified_Codes_Sent",
"Dependency_Unavailable",
"System_Failure",
"Service_Unavailable"
],
"example": "Request_Validation"
}
}
},
"example": {
"code": 409,
"domain": "Auth",
"message": "Buyer Conflict",
"reason": "Conflict"
}
}
}
},
"503": {
"description": "Response for Auth errors",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Default error model for Auth errors",
"allOf": [
{
"required": [
"code",
"domain",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "The underlying http status code",
"format": "int32",
"example": 500
},
"message": {
"type": "string",
"description": "A simple message in english describing the error and can be returned to the consumer",
"example": "Age cannot be less than 18"
},
"domain": {
"type": "string",
"description": "The domain where the error is originating from as defined by the service",
"example": "Payments"
},
"metadata": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Any additional details to be conveyed as determined by the service. If present, will return map of key value pairs",
"example": {
"propertyName": "propertyName is required"
}
}
}
}
],
"properties": {
"reason": {
"type": "string",
"description": "Auth error reason codes",
"default": "Request_Validation",
"enum": [
"Request_Validation",
"Not_Found",
"Unauthenticated",
"Unauthenticated_Retry_With_PII",
"Unauthenticated_Buyer_Mismatch",
"Unauthenticated_Buyer_Not_Found",
"Invalid_Token",
"Too_Many_Code_Attempts",
"Too_Many_Unverified_Codes_Sent",
"Dependency_Unavailable",
"System_Failure",
"Service_Unavailable"
],
"example": "Request_Validation"
}
}
},
"example": {
"code": 400,
"message": "Error(s) in payload",
"domain": "Auth",
"metadata": {
"email": "required"
},
"reason": "Request_Validation"
}
}
}
}
}
}
},
"/api/auth/code": {
"get": {
"security": [
{
"bearerAuth": [
"r:otp"
]
}
],
"description": "Allows a user to list OTP codes using filtering query parameters.\n\nA user can search by phone, email, buyerID, and/or tenantID. If present on the JWT, the buyerID/tenantID claims are automatically added to the search parameters. To filter by verified OTP codes, add `&verifiedCodeOnly` to query.\n\nFor a valid request, at least one of the `buyerID.eq`, `phone.eq` or `email.eq` filters is required.",
"tags": [
"Auth"
],
"summary": "List codes",
"operationId": "listCodes",
"parameters": [
{
"description": "Searches exact matches on buyerID. Must be URI encoded.",
"name": "buyerID.eq",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"example": "15f26406-09db-49bb-a715-0a41c20cbef1"
},
{
"description": "Searches exact matches on phone. Must be URI encoded.",
"name": "phone.eq",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"example": "+19667079543"
},
{
"description": "Searches exact matches on email. Must be URI encoded.",
"name": "email.eq",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"example": "automation%2b8c340e1ff6e6935ce638@breadpayments.com"
},
{
"description": "Filters the response to only include a record in the response if the code is verified.",
"name": "verifiedCodeOnly",
"in": "query",
"required": false,
"allowEmptyValue": true,
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "limit",
"description": "The maximum number of records that will be returned in a result set.",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"default": 10
},
"example": 50
},
{
"in": "query",
"name": "offset",
"description": "The number of records to skip before starting to collect the result set. Used in conjunction with limit query parameter for pagination support",
"required": false,
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"example": 20
}
],
"responses": {
"200": {
"description": "A list of buyers that match the filtering criteria.",
"content": {
"application/json": {
"schema": {
"description": "A list of Code records including pagination response fields.",
"type": "object",
"properties": {
"codes": {
"type": "array",
"items": {
"description": "Code represents an OTP code record",
"type": "object",
"properties": {
"id": {
"description": "Unique ID associated with this code.",
"type": "string",
"format": "uuid",
"example": "c3f8e97b-2d09-4cb8-a41e-c5b635b0f1e3",
"readOnly": true
},
"tenantID": {
"description": "The tenantID associated with the X-Bread-APP-ID header passed to /api/send-code.",
"type": "string",
"format": "uuid",
"example": "c3f8e97b-2d09-4cb8-a41e-c5b635b0f1e3",
"readOnly": true
},
"buyerID": {
"description": "The ID of the buyer who verified this OTP code using phone or email.",
"type": "string",
"format": "uuid",
"example": "c3f8e97b-2d09-4cb8-a41e-c5b635b0f1e3"
},
"ip": {
"description": "The IP of the buyer who verified this OTP code.",
"type": "string",
"format": "ipv4",
"example": "127.0.0.1"
},
"loginPIIMismatch": {
"description": "A nullable boolean represented whether or not a PII mismatch occured during login.",
"type": "boolean",
"readOnly": true
},
"phone": {
"description": "The phone number provided to /api/send-code.",
"allOf": [
{
"type": "string",
"description": "Telephone number including country code",
"example": "+14539842345"
}
]
},
"email": {
"description": "The email address provided to /api/send-code.",
"allOf": [
{
"type": "string",
# --- truncated at 32 KB (349 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bread-financial/refs/heads/main/openapi/bread-foundations-openapi.json