openapi: 3.0.3 info: title: Reseller Callback API description: | Specification for reseller callback endpoints that receive certificate and account status notifications from Identrust. Identrust POSTs JSON to the callback URL and bearer token you provide during onboarding. The URL path is yours to define (for example `/callback`). version: 1.0.0 contact: name: Identrust HUES Platform servers: - url: https://{resellerHost} description: Your callback endpoint. Use the URL you registered with Identrust. variables: resellerHost: default: api.example.com description: Hostname of your callback service tags: - name: Callbacks description: Status notifications delivered to your callback endpoint paths: /callback: post: tags: - Callbacks summary: Receive status notification description: | Identrust sends a `POST` request with `Content-Type: application/json` and `Accept: application/json`. The request body is one of two notification types: certificate status or account status. All JSON property names use snake_case. Distinguish notification types by payload shape — certificate notifications include a `data` object; account notifications do not. Authenticate using the bearer token Identrust issued to you during onboarding. Return any HTTP `2xx` status to acknowledge receipt. The response body is ignored. Non-2xx responses are retried with exponential backoff. Identrust waits up to 30 seconds for a response before treating the call as failed. operationId: receiveResellerCallback security: - bearerAuth: [] requestBody: required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/CertificateStatusNotification' - $ref: '#/components/schemas/AccountStatusNotification' examples: certificateIssued: summary: Certificate status notification value: id: idempotent-event-id-123 event_type: Certificate status: issued created: 1719859200000 data: certificate: id: certificate-id-456 ca_certificate: "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" certificate: "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" status: issued order: lookup: order-lookup-123 profile_code: TLS-90d expires: 1727635200000 status: issued account: lookup: account-lookup-123 customer_email: customer@example.com eab: kid: kid-123 customer_email: customer@example.com accountSuspended: summary: Account status notification value: event_type: AccountStatus reason: ACCOUNT_SUSPENDED message: Account suspended due to policy violation account_lookup: account-lookup-123 eab_kid: kid-123 responses: '200': description: Notification accepted. Any 2xx status code is treated as success. '204': description: Notification accepted with no content. '4XX': description: Client error. Identrust will retry delivery. '5XX': description: Server error. Identrust will retry delivery. components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: | Bearer token issued to you by Identrust during onboarding, sent as `Authorization: Bearer `. schemas: CertificateStatusNotification: type: object description: | Notification of a certificate or order status change. Distinguished from account notifications by the presence of `event_type` and `data`. Null fields are omitted from the JSON body. required: - data properties: id: type: string description: Idempotent event identifier. Use this to deduplicate retries. example: idempotent-event-id-123 event_type: type: string description: Notification type. example: Certificate status: type: string description: Certificate or order status (for example `issued` or `revoked`). example: issued created: type: integer format: int64 description: Event creation time as Unix epoch milliseconds. example: 1719859200000 data: $ref: '#/components/schemas/CertificateStatusData' CertificateStatusData: type: object description: | Always present on certificate notifications. Nested objects other than `certificate` are included only when Identrust has that data. required: - certificate properties: certificate: $ref: '#/components/schemas/Certificate' order: $ref: '#/components/schemas/OrderSummary' account: $ref: '#/components/schemas/AccountSummary' eab: $ref: '#/components/schemas/EabSummary' Certificate: type: object description: | Always present under `data`, but individual properties are omitted when not applicable (for example on revocation, PEM fields may be absent). properties: id: type: string description: Certificate identifier. example: certificate-id-456 ca_certificate: type: string description: PEM-encoded CA certificate chain. certificate: type: string description: PEM-encoded end-entity certificate. status: type: string description: Certificate status. example: issued OrderSummary: type: object properties: lookup: type: string description: Order lookup identifier. example: order-lookup-123 profile_code: type: string description: Certificate profile code. example: TLS-90d expires: type: integer format: int64 description: Order expiry time as Unix epoch milliseconds. example: 1727635200000 status: type: string description: Order status. example: issued AccountSummary: type: object properties: lookup: type: string description: Account lookup identifier. example: account-lookup-123 customer_email: type: string format: email description: Customer email address associated with the account. example: customer@example.com deleted: type: boolean description: Whether the account has been deleted. suspended: type: boolean description: Whether the account is suspended. EabSummary: type: object properties: kid: type: string description: External account binding key identifier. example: kid-123 customer_email: type: string format: email description: Customer email address associated with the EAB. example: customer@example.com deleted: type: boolean description: Whether the EAB has been deleted. suspended: type: boolean description: Whether the EAB is suspended. AccountStatusNotification: type: object description: | Notification of an account status change. Distinguished from certificate notifications by the absence of `data`. Null fields are omitted from the JSON body. No fields are guaranteed on every delivery; handle absent properties gracefully. properties: event_type: type: string description: Notification type. example: AccountStatus reason: $ref: '#/components/schemas/AccountStatusReason' message: type: string description: Human-readable status message. example: Account suspended due to policy violation account_lookup: type: string description: Account lookup identifier. example: account-lookup-123 eab_kid: type: string description: External account binding key identifier, when applicable. example: kid-123 AccountStatusReason: type: string enum: - ACCOUNT_SUSPENDED - RATE_LIMIT_EXCEEDED description: Reason for the account status notification.