asyncapi: 2.6.0 info: title: Okta Event Hooks and Log Streams version: '1.0.0' description: | AsyncAPI description of Okta's two outbound event delivery surfaces: 1. **Event Hooks** — Okta POSTs a CloudEvents-style envelope to a customer-owned HTTPS endpoint whenever a subscribed System Log event type fires. Subscribers register an endpoint, choose from event types in the Event Types catalog (filtered by `event-hook-eligible`), and complete a one-time GET verification handshake before deliveries begin. 2. **Log Streams** — Okta streams the full System Log feed to a managed destination (AWS EventBridge or Splunk Cloud) configured through the `/api/v1/logStreams` Management API. Field names, enums, and constraints in this document are drawn verbatim from the Okta Event Hooks concept documentation and the Okta Management OpenAPI spec (`okta/okta-management-openapi-spec`, `dist/current/management-minimal.yaml`). contact: name: Okta Developer Experience url: https://developer.okta.com/docs/concepts/event-hooks/ license: name: Okta Developer Terms url: https://developer.okta.com/terms/ termsOfService: https://developer.okta.com/terms/ x-source-documentation: - https://developer.okta.com/docs/concepts/event-hooks/ - https://developer.okta.com/docs/reference/api/event-types/ - https://github.com/okta/okta-management-openapi-spec/blob/master/dist/current/management-minimal.yaml defaultContentType: application/json servers: customerWebhook: url: '{customerEndpoint}' protocol: https description: | Customer-operated HTTPS endpoint that receives Okta Event Hook deliveries. Must be internet-accessible, respond within a three-second timeout, and reply with HTTP 200 or 204. The path is registered as `channel.config.uri` on the Event Hook object. variables: customerEndpoint: description: Fully-qualified HTTPS URL registered with Okta. default: https://your-service.example.com/okta/event-hook awsEventBridge: url: events.{awsRegion}.amazonaws.com protocol: https description: | AWS EventBridge endpoint that receives the System Log stream when a Log Stream object of type `aws_eventbridge` is provisioned. The actual partner event source name and AWS account are configured in `LogStreamSettingsAws`. variables: awsRegion: description: AWS region of the EventBridge partner event source. enum: - ap-northeast-1 - ap-northeast-2 - ap-northeast-3 - ap-south-1 - ap-southeast-1 - ap-southeast-2 - ca-central-1 - eu-central-1 - eu-north-1 - eu-west-1 - eu-west-2 - eu-west-3 - sa-east-1 - us-east-1 - us-east-2 - us-west-1 - us-west-2 default: us-east-1 splunkCloud: url: '{splunkHost}' protocol: https description: | Splunk Cloud HTTP Event Collector (HEC) endpoint that receives the System Log stream when a Log Stream object of type `splunk_cloud_logstreaming` is provisioned. Configured by `LogStreamSettingsSplunk` (`host`, `edition`, `token`). variables: splunkHost: description: Splunk Cloud domain (no scheme), e.g. acme.splunkcloud.com. default: acme.splunkcloud.com channels: okta/event-hook/verification: description: | One-time verification handshake. After an Event Hook is created (or its endpoint URL changes), Okta sends a single HTTP GET request to the registered endpoint with an `x-okta-verification-challenge` header. The endpoint must echo the header value back in a JSON body under the property `verification`. The Event Hook's `verificationStatus` transitions from `UNVERIFIED` to `VERIFIED` on success. `UNVERIFIED` event hooks won't receive any events. bindings: http: type: request method: GET subscribe: operationId: receiveEventHookVerification summary: Receive the one-time verification GET from Okta. bindings: http: type: request method: GET message: $ref: '#/components/messages/EventHookVerificationChallenge' publish: operationId: respondEventHookVerification summary: Echo the challenge value in a JSON body to complete verification. message: $ref: '#/components/messages/EventHookVerificationResponse' okta/event-hook/delivery: description: | Event Hook delivery channel. Okta POSTs a CloudEvents 0.1-style envelope to the registered endpoint each time one of the subscribed event types fires. The body contains a `data.events` array of `LogEvent` objects — the same shape returned by the System Log API. Authentication is via a customer-chosen `Authorization` header value (the `EventHookChannelConfigAuthScheme` with `type: HEADER`). bindings: http: type: request method: POST subscribe: operationId: receiveEventHookDelivery summary: Receive a batch of subscribed System Log events. bindings: http: type: request method: POST message: $ref: '#/components/messages/EventHookDelivery' okta/log-stream/aws-eventbridge: description: | System Log events streamed to an AWS EventBridge partner event source. Okta manages the stream when a `LogStream` resource of type `aws_eventbridge` is ACTIVE; payloads are individual `LogEvent` objects. subscribe: operationId: receiveLogStreamEventBridge summary: Receive a System Log event via AWS EventBridge. message: $ref: '#/components/messages/LogStreamEvent' okta/log-stream/splunk-cloud: description: | System Log events streamed to a Splunk Cloud HTTP Event Collector. Okta manages the stream when a `LogStream` resource of type `splunk_cloud_logstreaming` is ACTIVE; payloads are individual `LogEvent` objects wrapped per HEC conventions by Okta. subscribe: operationId: receiveLogStreamSplunk summary: Receive a System Log event via Splunk Cloud HEC. message: $ref: '#/components/messages/LogStreamEvent' components: messages: EventHookVerificationChallenge: name: EventHookVerificationChallenge title: Okta Event Hook one-time verification challenge summary: | The single GET request Okta sends to confirm endpoint ownership. The challenge value is in the `x-okta-verification-challenge` header; no request body is sent. contentType: application/json bindings: http: headers: type: object properties: x-okta-verification-challenge: type: string description: | Random challenge string Okta expects the endpoint to echo back in the JSON response body. required: - x-okta-verification-challenge payload: type: 'null' description: Verification GET requests have no request body. EventHookVerificationResponse: name: EventHookVerificationResponse title: Okta Event Hook verification response summary: | JSON body the endpoint must return to complete verification — a single property `verification` containing the value of the `x-okta-verification-challenge` header from the GET request. contentType: application/json payload: $ref: '#/components/schemas/EventHookVerificationResponseBody' EventHookDelivery: name: EventHookDelivery title: Okta Event Hook delivery envelope summary: | CloudEvents 0.1-style envelope that Okta POSTs for every batch of subscribed System Log events. Sent with the customer's chosen `Authorization` header value and `Content-Type: application/json`. contentType: application/json bindings: http: headers: type: object properties: Authorization: type: string description: | Customer-defined secret value registered as the Event Hook's `channel.config.authScheme.value` (`type: HEADER`). Okta sends this header on every delivery so the receiver can authenticate the call. Content-Type: type: string const: application/json Accept: type: string const: application/json required: - Authorization - Content-Type payload: $ref: '#/components/schemas/EventHookDeliveryEnvelope' LogStreamEvent: name: LogStreamEvent title: Okta System Log event delivered via Log Stream summary: | Individual `LogEvent` object emitted to the configured Log Stream destination (AWS EventBridge or Splunk Cloud). contentType: application/json payload: $ref: '#/components/schemas/LogEvent' schemas: EventHookVerificationResponseBody: type: object description: | Body returned by the customer endpoint to complete the verification handshake. properties: verification: type: string description: Echoed value of the `x-okta-verification-challenge` header. required: - verification example: verification: 'OKTA-VERIFICATION-CHALLENGE-VALUE-RECEIVED-IN-HEADER' EventHookDeliveryEnvelope: type: object description: | CloudEvents 0.1-style envelope. Field names taken verbatim from the Okta Event Hooks concept documentation. properties: eventType: type: string const: com.okta.event_hook description: Always `com.okta.event_hook` for Event Hook deliveries. eventTypeVersion: type: string const: '1.0' description: Version of the Event Hook envelope schema. cloudEventsVersion: type: string const: '0.1' description: CloudEvents specification version implemented by Okta. source: type: string format: uri description: | URI identifying the Event Hook that produced the delivery, e.g. `https://{yourOktaDomain}/api/v1/eventHooks/{eventHookId}`. eventId: type: string description: Unique identifier for this delivery. eventTime: type: string format: date-time description: ISO 8601 timestamp when Okta generated the delivery. contentType: type: string const: application/json data: $ref: '#/components/schemas/EventHookDeliveryData' required: - eventType - eventTypeVersion - cloudEventsVersion - source - eventId - eventTime - contentType - data EventHookDeliveryData: type: object description: | Payload wrapper. The `events` array contains one or more `LogEvent` objects matching the subscriber's `EventSubscriptions.items` list. properties: events: type: array description: | Batch of System Log events. The content of each array element is a `LogEvent` object — the same object the System Log API defines. items: $ref: '#/components/schemas/LogEvent' required: - events LogEvent: type: object description: | System Log event as delivered by both Event Hooks (inside `data.events[]`) and Log Streams. Top-level field set taken verbatim from the Okta Event Hooks concept sample payload. properties: uuid: type: string description: Unique identifier for the event. published: type: string format: date-time description: Timestamp when Okta published the event. eventType: type: string description: | Dotted event type from the Okta Event Types catalog. See `EventHookEligibleEventType` for known event-hook-eligible values. version: type: string description: Version of the LogEvent schema. displayMessage: type: string description: Human-readable description of the event. severity: type: string description: Event severity (e.g. INFO, WARN, ERROR). legacyEventType: type: string description: Legacy event identifier preserved for backward compatibility. actor: $ref: '#/components/schemas/LogActor' client: $ref: '#/components/schemas/LogClient' device: type: object description: Device context, when available. additionalProperties: true outcome: type: object description: Outcome of the event (e.g. result, reason). additionalProperties: true target: type: array description: | Objects acted upon by the event. Element shape mirrors the System Log `LogTarget` schema. items: type: object additionalProperties: true transaction: type: object description: Transaction context (id, type). additionalProperties: true debugContext: type: object description: Debug context for the event. additionalProperties: true authenticationContext: type: object description: Authentication context for the actor. additionalProperties: true securityContext: type: object description: Security context (ISP, geo enrichment). additionalProperties: true insertionTimestamp: type: string format: date-time description: Timestamp Okta inserted the event into the System Log. required: - uuid - published - eventType - version LogActor: type: object description: | Actor that initiated the event. Field set taken from the Event Hooks concept sample payload. properties: id: type: string type: type: string alternateId: type: string displayName: type: string detailEntry: type: object additionalProperties: true LogClient: type: object description: | Client context (user agent, network location). Field set taken from the Event Hooks concept sample payload. properties: userAgent: type: object properties: rawUserAgent: type: string os: type: string browser: type: string zone: type: string device: type: string id: type: string ipAddress: type: string geographicalContext: type: object properties: city: type: string state: type: string country: type: string postalCode: type: string geolocation: type: object properties: lat: type: number lon: type: number ipChain: type: array items: type: object additionalProperties: true EventHookEligibleEventType: type: string description: | Verified event-hook-eligible event types pulled from the Okta Event Types catalog. This is an open list — Okta adds new eligible event types over time; consult the live catalog and filter by `event-hook-eligible` for the canonical set. enum: # Access requests & reviews - access.request.cancel - access.request.condition.activate - access.request.condition.create - access.request.condition.deactivate - access.request.condition.delete - access.request.condition.invalidate - access.request.condition.update - access.request.create - access.request.expire - access.request.reject - access.request.resolve - access.request.sequence.create - access.request.sequence.delete - access.request.sequence.update - access.request.settings.update - access.request.update - access.review.action - access.review.close - access.review.create - access.review.remediate - access.review.start - access.review.update # Application events - app.access_request.approver.approve - app.access_request.approver.deny - app.access_request.delete - app.access_request.deny - app.access_request.expire - app.access_request.grant - app.access_request.request - app.ad.password_migration_campaign.user.migrate.end - app.interclient_mapping.create - app.interclient_mapping.delete - app.interclient_mapping.delete_all - app.oauth2.as.consent.grant - app.oauth2.as.consent.revoke - app.oauth2.as.consent.revoke.implicit.as - app.oauth2.as.consent.revoke.implicit.client - app.oauth2.as.consent.revoke.implicit.scope - app.oauth2.as.consent.revoke.implicit.user - app.oauth2.as.consent.revoke.user - app.oauth2.as.consent.revoke.user.client - app.oauth2.as.token.grant.access_token - app.oauth2.as.token.grant.interclient_token - app.oauth2.client.privilege.grant - app.oauth2.client.privilege.revoke - app.oauth2.token.grant.interclient_token - app.oauth2.trusted_server.add - app.oauth2.trusted_server.delete - app.user_management - app.user_management.user_group_import.upsert_success - application.lifecycle.activate - application.lifecycle.create - application.lifecycle.deactivate - application.lifecycle.delete - application.lifecycle.update - application.policy.sign_on.deny_access - application.provision.group_push.mapping.update.or.delete.failed.with.error - application.provision.user.import_profile - application.provision.user.push - application.provision.user.push_profile - application.provision.user.reactivate - application.provision.user.sync - application.user_membership.add - application.user_membership.change_password - application.user_membership.remove - application.user_membership.update # Certification campaigns - certification.campaign.close - certification.campaign.context.update - certification.campaign.item.decide - certification.campaign.item.remediate - certification.campaign.launch # Device lifecycle - device.enrollment.create - device.lifecycle.activate - device.lifecycle.deactivate - device.lifecycle.delete - device.lifecycle.suspend - device.lifecycle.unsuspend # User lifecycle - user.lifecycle.activate - user.lifecycle.create - user.lifecycle.deactivate - user.lifecycle.delete - user.lifecycle.suspend - user.lifecycle.unsuspend - user.lifecycle.update # User account - user.account.update_password - user.account.change_recovery_question - user.account.reset_password # User MFA factors - user.mfa.factor.activate - user.mfa.factor.deactivate - user.mfa.factor.delete - user.mfa.factor.update # User sessions - user.session.start - user.session.end - user.session.extend # Group membership / lifecycle - group.user_membership.add - group.user_membership.remove - group.lifecycle.create - group.lifecycle.update - group.lifecycle.delete # Policy lifecycle - policy.lifecycle.create - policy.lifecycle.update - policy.lifecycle.delete # System API tokens - system.api_token.lifecycle.create - system.api_token.lifecycle.update - system.api_token.lifecycle.delete # Network zones - zone.lifecycle.create - zone.lifecycle.update - zone.lifecycle.delete # Directory integrations - directory.lifecycle.create - directory.lifecycle.update - directory.lifecycle.delete EventHookRegistration: type: object description: | Shape of an Event Hook resource as managed via `/api/v1/eventHooks`. Field names and enums taken verbatim from the Okta Management OpenAPI spec (schema `EventHook`). properties: name: type: string description: Display name for the event hook. description: type: string nullable: true status: type: string enum: - ACTIVE - INACTIVE verificationStatus: type: string enum: - UNVERIFIED - VERIFIED events: $ref: '#/components/schemas/EventSubscriptions' channel: $ref: '#/components/schemas/EventHookChannel' id: type: string created: type: string format: date-time createdBy: type: string lastUpdated: type: string format: date-time required: - name - events - channel EventSubscriptions: type: object description: Subscription block on an Event Hook resource. properties: type: type: string enum: - EVENT_TYPE description: The events object type. Currently supports `EVENT_TYPE`. items: type: array items: $ref: '#/components/schemas/EventHookEligibleEventType' description: Subscribed event types that trigger the event hook. filter: type: object nullable: true description: | Optional Okta Expression Language filter (EA). See `EventHookFilters` in the Management OpenAPI spec. required: - type - items EventHookChannel: type: object description: Delivery channel for an Event Hook resource. properties: type: type: string enum: - HTTP description: The channel type. Currently supports `HTTP`. version: type: string const: 1.0.0 description: Channel version. Currently the only supported version is `1.0.0`. config: $ref: '#/components/schemas/EventHookChannelConfig' required: - type - version - config EventHookChannelConfig: type: object properties: uri: type: string format: uri description: HTTPS endpoint Okta calls to deliver the event hook. method: type: string readOnly: true description: HTTP method Okta uses (POST for delivery). headers: type: array items: type: object properties: key: type: string value: type: string authScheme: type: object properties: type: type: string enum: - HEADER description: Currently only `HEADER` is supported. key: type: string description: Header name (e.g. `Authorization`). value: type: string writeOnly: true description: | Secret value Okta sends in the named header on every delivery. Not returned in API responses. required: - uri LogStream: type: object description: | Log Stream resource managed via `/api/v1/logStreams`. Schema and enum values are taken verbatim from `LogStream`, `LogStreamType`, and `LogStreamLinksSelfAndLifecycle` in the Okta Management OpenAPI spec. properties: id: type: string readOnly: true name: type: string description: Unique name for the log stream object. type: type: string enum: - aws_eventbridge - splunk_cloud_logstreaming description: | Streaming provider. `aws_eventbridge` → AWS EventBridge; `splunk_cloud_logstreaming` → Splunk Cloud. status: type: string enum: - ACTIVE - INACTIVE readOnly: true created: type: string format: date-time readOnly: true lastUpdated: type: string format: date-time readOnly: true settings: oneOf: - $ref: '#/components/schemas/LogStreamSettingsAws' - $ref: '#/components/schemas/LogStreamSettingsSplunk' required: - name - type - status - settings LogStreamSettingsAws: type: object description: | Configuration for a `aws_eventbridge` Log Stream. Cannot be modified after creation. Field names verbatim from `LogStreamSettingsAws`. properties: accountId: type: string minLength: 12 maxLength: 12 description: Your AWS account ID. example: '123456789012' eventSourceName: type: string minLength: 1 maxLength: 75 description: | Alphanumeric name (no spaces) identifying this event source in AWS EventBridge. example: your-event-source-name region: type: string description: Destination AWS region where the event source lives. enum: - ap-northeast-1 - ap-northeast-2 - ap-northeast-3 - ap-south-1 - ap-southeast-1 - ap-southeast-2 - ca-central-1 - eu-central-1 - eu-north-1 - eu-west-1 - eu-west-2 - eu-west-3 - sa-east-1 - us-east-1 - us-east-2 - us-west-1 - us-west-2 required: - accountId - eventSourceName - region LogStreamSettingsSplunk: type: object description: | Configuration for a `splunk_cloud_logstreaming` Log Stream. Field names verbatim from `LogStreamSettingsSplunk`. properties: host: type: string minLength: 17 maxLength: 116 description: | Splunk Cloud domain (no `http`/`https` scheme), e.g. `acme.splunkcloud.com`. example: acme.splunkcloud.com edition: type: string enum: - aws - aws_govcloud - gcp description: Splunk Cloud edition. token: type: string writeOnly: true description: | Splunk HEC token. Set at object creation but not returned in API responses. example: 11111111-1111-2222-2222-222222222222 required: - host - edition - token