Customer Planned contract

Exchange an authorization code or rotate a refresh token

Exchanges a single-use code created only after SMOKESTACK customer authentication and consent, or rotates a grant-bound refresh token. Every invalid, expired, replayed, denied, absent-match, and ambiguous-match outcome is externally collapsed to invalid_grant.

Runtime status: unavailable. This is a source contract, not a live access or availability guarantee. Learn more

POST/partner/customer-connections/v1/subject-tokens

Authority

Profile: partner
Data class: customer_personal
Required operation: exchangePartnerCustomerSubjectToken
Subject scopes: No subject scopes declared for this operation.

partnerServiceBearer security scheme

{
  "type": "http",
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "description": "Short-lived, server-only partner credential used for capabilities, intent creation, and token exchange. Purpose \"partner-customer-connections\", audience \"partner-customer-connections-service\", and operation scope \"customer-connections:partner:<operationId>\" are exact validation inputs. Claims: assignmentId, aud, exp, iat, iss, jti, operation, partnerId, purpose, sub, tenantId, tokenUse. It reaches no customer data on its own."
}

Request

Request parameters
Parameter	Location	Requirement	Schema
`smokestack-api-version`	header	Required	`{"type":"string","const":"2026-08-24"}`
`x-request-id`	header	Optional	`{"type":"string","minLength":1,"maxLength":200}`
`x-correlation-id`	header	Optional	`{"type":"string","minLength":1,"maxLength":200}`
`idempotency-key`	header	Required	`{"type":"string","minLength":16,"maxLength":200}`

Request body

{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PartnerCustomerSubjectTokenRequest"
      }
    }
  }
}

Idempotency

{
  "required": true,
  "retentionSeconds": 604800,
  "replay": "same scoped key and canonical payload returns the stored business status and payload",
  "conflict": "same scoped key with a different canonical payload returns idempotency_conflict"
}

Request examples

Templates for your server, not browser code. Replace every placeholder and use your approved origin. For requests with a body, construct request.json / requestBody / request_body from the schema.

Language

# Replace placeholders using your approved server-side integration.
curl --request POST 'https://partner-api.invalid/partner/customer-connections/v1/subject-tokens' \
  --header 'smokestack-api-version: 2026-08-24' \
  --header 'idempotency-key: <IDEMPOTENCY_KEY>' \
  --header 'Authorization: Bearer <SERVER_ONLY_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data @request.json

Responses

200 Successful response within the operation's declared authority and data class.

{
  "description": "Successful response within the operation's declared authority and data class.",
  "headers": {
    "SMOKESTACK-API-Version": {
      "description": "The negotiated compatible contract revision.",
      "schema": {
        "type": "string",
        "const": "2026-08-24"
      }
    },
    "X-Request-ID": {
      "description": "The request identifier accepted from the caller or generated by SMOKESTACK.",
      "schema": {
        "type": "string"
      }
    },
    "X-Correlation-ID": {
      "description": "The end-to-end correlation identifier.",
      "schema": {
        "type": "string"
      }
    },
    "Deprecation": {
      "description": "RFC 9745 Structured Field Date when an operation or revision is deprecated.",
      "schema": {
        "type": "string"
      }
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PartnerCustomerSubjectTokenResponse"
      }
    }
  }
}

400 Malformed input or generic invalid_grant. The response never distinguishes denial, absence, ambiguity, expiration, or replay.

{
  "description": "Malformed input or generic invalid_grant. The response never distinguishes denial, absence, ambiguity, expiration, or replay.",
  "headers": {
    "SMOKESTACK-API-Version": {
      "description": "The negotiated compatible contract revision.",
      "schema": {
        "type": "string",
        "const": "2026-08-24"
      }
    },
    "X-Request-ID": {
      "description": "The request identifier accepted from the caller or generated by SMOKESTACK.",
      "schema": {
        "type": "string"
      }
    },
    "X-Correlation-ID": {
      "description": "The end-to-end correlation identifier.",
      "schema": {
        "type": "string"
      }
    },
    "Deprecation": {
      "description": "RFC 9745 Structured Field Date when an operation or revision is deprecated.",
      "schema": {
        "type": "string"
      }
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PartnerCustomerError"
      }
    }
  }
}

401 The required partner or subject credential is missing or invalid.

{
  "description": "The required partner or subject credential is missing or invalid.",
  "headers": {
    "SMOKESTACK-API-Version": {
      "description": "The negotiated compatible contract revision.",
      "schema": {
        "type": "string",
        "const": "2026-08-24"
      }
    },
    "X-Request-ID": {
      "description": "The request identifier accepted from the caller or generated by SMOKESTACK.",
      "schema": {
        "type": "string"
      }
    },
    "X-Correlation-ID": {
      "description": "The end-to-end correlation identifier.",
      "schema": {
        "type": "string"
      }
    },
    "Deprecation": {
      "description": "RFC 9745 Structured Field Date when an operation or revision is deprecated.",
      "schema": {
        "type": "string"
      }
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PartnerCustomerError"
      }
    }
  }
}

403 The partner credential lacks authority for this operation; no customer or match state is disclosed.

{
  "description": "The partner credential lacks authority for this operation; no customer or match state is disclosed.",
  "headers": {
    "SMOKESTACK-API-Version": {
      "description": "The negotiated compatible contract revision.",
      "schema": {
        "type": "string",
        "const": "2026-08-24"
      }
    },
    "X-Request-ID": {
      "description": "The request identifier accepted from the caller or generated by SMOKESTACK.",
      "schema": {
        "type": "string"
      }
    },
    "X-Correlation-ID": {
      "description": "The end-to-end correlation identifier.",
      "schema": {
        "type": "string"
      }
    },
    "Deprecation": {
      "description": "RFC 9745 Structured Field Date when an operation or revision is deprecated.",
      "schema": {
        "type": "string"
      }
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PartnerCustomerError"
      }
    }
  }
}

406 The requested contract revision is unsupported.

{
  "description": "The requested contract revision is unsupported.",
  "headers": {
    "SMOKESTACK-API-Version": {
      "description": "The negotiated compatible contract revision.",
      "schema": {
        "type": "string",
        "const": "2026-08-24"
      }
    },
    "X-Request-ID": {
      "description": "The request identifier accepted from the caller or generated by SMOKESTACK.",
      "schema": {
        "type": "string"
      }
    },
    "X-Correlation-ID": {
      "description": "The end-to-end correlation identifier.",
      "schema": {
        "type": "string"
      }
    },
    "Deprecation": {
      "description": "RFC 9745 Structured Field Date when an operation or revision is deprecated.",
      "schema": {
        "type": "string"
      }
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PartnerCustomerError"
      }
    }
  }
}

409 The idempotency key was reused with a different canonical payload.

{
  "description": "The idempotency key was reused with a different canonical payload.",
  "headers": {
    "SMOKESTACK-API-Version": {
      "description": "The negotiated compatible contract revision.",
      "schema": {
        "type": "string",
        "const": "2026-08-24"
      }
    },
    "X-Request-ID": {
      "description": "The request identifier accepted from the caller or generated by SMOKESTACK.",
      "schema": {
        "type": "string"
      }
    },
    "X-Correlation-ID": {
      "description": "The end-to-end correlation identifier.",
      "schema": {
        "type": "string"
      }
    },
    "Deprecation": {
      "description": "RFC 9745 Structured Field Date when an operation or revision is deprecated.",
      "schema": {
        "type": "string"
      }
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PartnerCustomerError"
      }
    }
  }
}

429 Partner, external-subject, intent, or pairwise-subject rate limit exceeded.

{
  "description": "Partner, external-subject, intent, or pairwise-subject rate limit exceeded.",
  "headers": {
    "SMOKESTACK-API-Version": {
      "description": "The negotiated compatible contract revision.",
      "schema": {
        "type": "string",
        "const": "2026-08-24"
      }
    },
    "X-Request-ID": {
      "description": "The request identifier accepted from the caller or generated by SMOKESTACK.",
      "schema": {
        "type": "string"
      }
    },
    "X-Correlation-ID": {
      "description": "The end-to-end correlation identifier.",
      "schema": {
        "type": "string"
      }
    },
    "Deprecation": {
      "description": "RFC 9745 Structured Field Date when an operation or revision is deprecated.",
      "schema": {
        "type": "string"
      }
    },
    "Retry-After": {
      "schema": {
        "type": "integer",
        "minimum": 0
      }
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PartnerCustomerError"
      }
    }
  }
}

500 Unexpected error without customer or match details.

{
  "description": "Unexpected error without customer or match details.",
  "headers": {
    "SMOKESTACK-API-Version": {
      "description": "The negotiated compatible contract revision.",
      "schema": {
        "type": "string",
        "const": "2026-08-24"
      }
    },
    "X-Request-ID": {
      "description": "The request identifier accepted from the caller or generated by SMOKESTACK.",
      "schema": {
        "type": "string"
      }
    },
    "X-Correlation-ID": {
      "description": "The end-to-end correlation identifier.",
      "schema": {
        "type": "string"
      }
    },
    "Deprecation": {
      "description": "RFC 9745 Structured Field Date when an operation or revision is deprecated.",
      "schema": {
        "type": "string"
      }
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PartnerCustomerError"
      }
    }
  }
}

503 An authoritative dependency is unavailable; the service does not guess.

{
  "description": "An authoritative dependency is unavailable; the service does not guess.",
  "headers": {
    "SMOKESTACK-API-Version": {
      "description": "The negotiated compatible contract revision.",
      "schema": {
        "type": "string",
        "const": "2026-08-24"
      }
    },
    "X-Request-ID": {
      "description": "The request identifier accepted from the caller or generated by SMOKESTACK.",
      "schema": {
        "type": "string"
      }
    },
    "X-Correlation-ID": {
      "description": "The end-to-end correlation identifier.",
      "schema": {
        "type": "string"
      }
    },
    "Deprecation": {
      "description": "RFC 9745 Structured Field Date when an operation or revision is deprecated.",
      "schema": {
        "type": "string"
      }
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PartnerCustomerError"
      }
    }
  }
}

Referenced schemas

Only schemas reachable from this operation are shown. The revision-pinned OpenAPI download includes their complete definitions.

PartnerCustomerSubjectTokenRequest

{
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "grantType": {
          "type": "string",
          "enum": [
            "authorization_code"
          ]
        },
        "authorizationCode": {
          "type": "string",
          "pattern": "^ccac_[A-Za-z0-9_-]{32,200}$"
        },
        "codeVerifier": {
          "type": "string",
          "pattern": "^[A-Za-z0-9._~-]{43,128}$"
        },
        "redirectUri": {
          "type": "string",
          "maxLength": 2048,
          "format": "uri"
        }
      },
      "required": [
        "grantType",
        "authorizationCode",
        "codeVerifier",
        "redirectUri"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "grantType": {
          "type": "string",
          "enum": [
            "refresh_token"
          ]
        },
        "refreshToken": {
          "type": "string",
          "pattern": "^ccrt_[A-Za-z0-9_-]{32,300}$"
        }
      },
      "required": [
        "grantType",
        "refreshToken"
      ],
      "additionalProperties": false
    }
  ]
}

PartnerCustomerSubjectTokenResponse

{
  "type": "object",
  "properties": {
    "tokenType": {
      "type": "string",
      "enum": [
        "Bearer"
      ]
    },
    "accessToken": {
      "type": "string",
      "minLength": 32,
      "maxLength": 4096
    },
    "expiresIn": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 900
    },
    "refreshToken": {
      "type": "string",
      "pattern": "^ccrt_[A-Za-z0-9_-]{32,300}$"
    },
    "refreshExpiresAt": {
      "type": "string",
      "format": "date-time"
    },
    "scope": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "customer.profile.basic",
          "customer.profile.contact",
          "customer.profile.birth_date",
          "customer.medical_eligibility.read"
        ]
      },
      "minItems": 1
    },
    "subject": {
      "type": "string",
      "pattern": "^cusub_v1_[A-Za-z0-9_-]{32,64}$"
    },
    "grantId": {
      "type": "string",
      "format": "uuid"
    },
    "meta": {
      "type": "object",
      "properties": {
        "apiVersion": {
          "type": "string",
          "enum": [
            "2026-08-24"
          ]
        },
        "requestId": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200
        },
        "generatedAt": {
          "type": "string",
          "format": "date-time"
        }
      },
      "required": [
        "apiVersion",
        "requestId",
        "generatedAt"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "tokenType",
    "accessToken",
    "expiresIn",
    "refreshToken",
    "refreshExpiresAt",
    "scope",
    "subject",
    "grantId",
    "meta"
  ],
  "additionalProperties": false
}

PartnerCustomerError

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "enum": [
        "invalid_request",
        "authentication_required",
        "permission_denied",
        "api_version_not_supported",
        "invalid_grant",
        "idempotency_conflict",
        "rate_limited",
        "dependency_unavailable",
        "internal_error"
      ]
    },
    "message": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500,
      "description": "Public, non-diagnostic message. invalid_grant must never describe customer or match state."
    },
    "requestId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "retryable": {
      "type": "boolean"
    }
  },
  "required": [
    "code",
    "message",
    "requestId",
    "retryable"
  ],
  "additionalProperties": false
}

← All Customer Connections API operations