> ## Documentation Index > Fetch the complete documentation index at: https://docs.yourflexpay.com/llms.txt > Use this file to discover all available pages before exploring further. # Rotate the calling application's full credential set > Generates a fresh client secret, webhook signing secret, and EC P-256 keypair for the authenticated application and returns the new credential material once. This endpoint returns credential material via `ApplicationCredentialsResponse`. **The clientSecret, webhookSecret, and privateJWK are returned only once** - store them securely. After rotation: - The previous client secret becomes invalid immediately. - The previous webhook secret becomes invalid immediately. - Switch will encrypt all outbound webhooks with the **new** public key. - Requests encrypted with the **old** public key will be rejected (Content-Encryption: JWE decryption will fail). - Allow a brief migration window for in-flight messages before destroying the old private key. The `keyVersion` field is incremented on each rotation. ## OpenAPI ````yaml /openapi/switch.openapi.json post /v1/applications/keys/rotate openapi: 3.0.1 info: title: Switch – Cross-Platform Tag-to-Tag Payment API description: > ## Overview Switch provides globally unique, portable identity **tags** that travel with users across applications. Each tag is a short handle (e.g. `@alice`) that can carry verified claims, participate in cross-application payments, and be federated to external identity providers. ## Key Capabilities - **Tags** – create, transfer, disable, and attach claims to identity handles. - **Cross-application payments** – send money from any tag on Application A to any tag on Application B; each application has a single escrow wallet tracked for end-of-day settlement. - **Ledger** – every completed payment produces an immutable double-entry `DEBIT` / `CREDIT` pair recorded against application wallets. - **Webhooks** – real-time callbacks with HMAC-SHA256 signatures and automatic retry (up to 3 attempts with exponential back-off). - **Settlement** – a scheduled end-of-day job aggregates daily wallet movements and emits `SETTLEMENT_BATCH` Kafka events. ## Authentication 1. Exchange credentials for a JWT: `POST /v1/auth/token` 2. Include the JWT as `Authorization: Bearer ` on all protected calls. ## Rate Limits | Endpoint | Limit | |---|---| | `POST /v1/auth/token` | 10 req / min per IP | | `POST /v1/transactions` | 60 req / min per application | | All other | 300 req / min per IP | contact: name: ReflexPay Platform Team url: https://yourflexpay.com email: integration@yourflexpay.com license: name: Proprietary url: https://yourflexpay.com/terms version: 1.0.0 servers: - url: https://staging-switch.yourflexpay.com/api description: Staging - url: https://switch.yourflexpay.com/api description: Production security: - bearerAuth: [] tags: - name: Authentication description: Exchange client credentials for a JWT access token. - name: Claims description: Attach and revoke verifiable claims on tags. - name: Encryption description: > JWE payload encryption – end-to-end security for API request bodies and webhook payloads. Each application receives an EC P-256 keypair at registration: - Switch encrypts **outbound webhooks** with the application's public key. - Applications encrypt **inbound request bodies** with the Switch public key. Algorithm: ECDH-ES+A256KW + A256GCM (JSON Web Encryption, RFC 7516). Use `GET /v1/keys/switch` to fetch the Switch public key. Use `POST /v1/applications/keys/rotate` to rotate your application keypair. - name: Authentication description: Exchange credentials for access tokens and rotate integration credentials - name: Settlement description: Query end-of-day settlement batches and per-application net positions. - name: Subjects description: Manage the real-world entities (users / organisations) behind tags. - name: Webhooks description: >- Inspect outbound webhook delivery records for transactions. Each transaction has at most two webhook records: one RECEIVER (sent on initiation) and one SENDER (sent on acceptance/rejection/expiry). - name: Admin Applications description: Administrative application provisioning and lifecycle endpoints. - name: Webhooks description: >- Inspect outbound webhook delivery records (RECEIVER and SENDER) for transactions. - name: Wallet description: View application escrow wallet balance and paginated ledger statement. - name: Wallet description: >- View application escrow wallet balance and paginated ledger statement (DEBIT / CREDIT entries). - name: Admin Entities description: >- Admin-only cross-entity record management: list, read, patch, and delete supported entities. - name: Encryption description: Public key distribution and keypair management for JWE payload encryption. - name: Consent description: Issue and manage user consent tokens for claim federation. - name: Transactions description: Initiate, accept/reject, and query cross-application tag-to-tag payments. - name: Tags description: Create, transfer, disable and resolve globally unique identity tags. externalDocs: description: Switch GitHub Repository url: https://github.com/reflexpay/switch paths: /v1/applications/keys/rotate: post: tags: - Authentication - Encryption summary: Rotate the calling application's full credential set description: > Generates a fresh client secret, webhook signing secret, and EC P-256 keypair for the authenticated application and returns the new credential material once. This endpoint returns credential material via `ApplicationCredentialsResponse`. **The clientSecret, webhookSecret, and privateJWK are returned only once** - store them securely. After rotation: - The previous client secret becomes invalid immediately. - The previous webhook secret becomes invalid immediately. - Switch will encrypt all outbound webhooks with the **new** public key. - Requests encrypted with the **old** public key will be rejected (Content-Encryption: JWE decryption will fail). - Allow a brief migration window for in-flight messages before destroying the old private key. The `keyVersion` field is incremented on each rotation. operationId: rotateKeys responses: '200': description: Credentials rotated - new credential material returned content: '*/*': schema: $ref: '#/components/schemas/ApiResponseApplicationCredentialsResponse' '401': description: Missing or invalid bearer token content: '*/*': schema: $ref: '#/components/schemas/ApiResponseApplicationCredentialsResponse' '500': description: Credential rotation failed content: '*/*': schema: $ref: '#/components/schemas/ApiResponseApplicationCredentialsResponse' components: schemas: ApiResponseApplicationCredentialsResponse: type: object properties: success: type: boolean message: type: string errorCode: type: string data: $ref: '#/components/schemas/ApplicationCredentialsResponse' errors: type: array items: type: string timestamp: type: string format: date-time ApplicationCredentialsResponse: type: object properties: clientId: type: string description: OAuth2-style client identifier (public) clientSecret: type: string description: Raw client secret. Returned only when application is created. readOnly: true webhookSecret: type: string description: Raw webhook signing secret readOnly: true publicJwk: $ref: '#/components/schemas/JwkDto' privateJwk: $ref: '#/components/schemas/JwkDto' keyVersion: type: integer description: Current keypair version. Incremented on each rotation. format: int32 example: 1 description: Application credentials JwkDto: type: object properties: kty: type: string crv: type: string x: type: string 'y': type: string use: type: string alg: type: string d: type: string description: EC P-256 private key in JWK format readOnly: true securitySchemes: bearerAuth: type: http description: > Obtain a token from `POST /v1/auth/token` using your `client_id` and `client_secret`, then enter `Bearer ` here. scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.