openapi: 3.1.1 info: title: WorkOS admin-portal radar API description: WorkOS REST API version: '1.0' contact: name: WorkOS url: https://workos.com email: support@workos.com license: name: MIT url: https://opensource.org/license/MIT servers: - url: https://api.workos.com description: Production - url: https://api.workos-test.com description: Staging security: - bearer: [] tags: - name: radar description: Radar fraud detection. x-displayName: Radar paths: /radar/attempts: post: description: Assess a request for risk using the Radar engine and receive a verdict. operationId: RadarStandaloneController_assess parameters: [] requestBody: required: true content: application/json: schema: type: object properties: ip_address: type: string description: The IP address of the request to assess. example: 49.78.240.97 user_agent: type: string description: The user agent string of the request to assess. example: Mozilla/5.0 email: type: string format: email description: The email address of the user making the request. example: user@example.com auth_method: type: string enum: - Password - Passkey - Authenticator - SMS_OTP - Email_OTP - Social - SSO - Other description: The authentication method being used. example: Password action: type: string enum: - login - signup - sign-up - sign-in - sign_up - sign_in - sign in - sign up description: The action being performed. example: login device_fingerprint: type: string description: An optional device fingerprint for the request. example: fp_abc123 bot_score: type: string description: An optional bot detection score for the request. example: '0.1' required: - ip_address - user_agent - email - auth_method - action responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/RadarStandaloneResponse' '400': description: Standalone radar is not enabled. content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Create an Attempt tags: - radar /radar/attempts/{id}: put: description: You may optionally inform Radar that an authentication attempt or challenge was successful using this endpoint. Some Radar controls depend on tracking recent successful attempts, such as impossible travel. operationId: RadarStandaloneController_updateRadarAttempt parameters: - name: id required: true in: path description: The unique identifier of the Radar attempt to update. schema: example: radar_att_01HZBC6N1EB1ZY7KG32X type: string requestBody: required: true content: application/json: schema: type: object properties: challenge_status: type: string description: Set to `"success"` to mark the challenge as completed. example: success const: success attempt_status: type: string description: Set to `"success"` to mark the authentication attempt as successful. example: success const: success responses: '204': description: Radar attempt updated. '400': description: Bad Request content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Update a Radar Attempt tags: - radar /radar/lists/{type}/{action}: post: description: Add an entry to a Radar list. operationId: RadarStandaloneController_updateRadarList parameters: - name: type required: true in: path description: The type of the Radar list (e.g. ip_address, domain, email). schema: type: string enum: - ip_address - domain - email - device - user_agent - device_fingerprint - country example: ip_address - name: action required: true in: path description: The list action indicating whether to add the entry to the allow or block list. schema: type: string enum: - block - allow example: block requestBody: required: true content: application/json: schema: type: object properties: entry: type: string description: The value to add to the list. Must match the format of the list type (e.g. a valid IP address for `ip_address`, a valid email for `email`). example: 198.51.100.42 required: - entry responses: '200': description: Entry already present in the list. content: application/json: schema: $ref: '#/components/schemas/RadarListEntryAlreadyPresentResponse' '201': description: Created '204': description: Entry successfully added to the list. '400': description: Bad Request content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Add an Entry to a Radar List tags: - radar delete: description: Remove an entry from a Radar list. operationId: RadarStandaloneController_deleteRadarListEntry parameters: - name: type required: true in: path description: The type of the Radar list (e.g. ip_address, domain, email). schema: type: string enum: - ip_address - domain - email - device - user_agent - device_fingerprint - country example: ip_address - name: action required: true in: path description: The list action indicating whether to remove the entry from the allow or block list. schema: type: string enum: - block - allow example: block requestBody: required: true content: application/json: schema: type: object properties: entry: type: string description: The value to remove from the list. Must match an existing entry. example: 198.51.100.42 required: - entry responses: '204': description: Radar list updated. '400': description: Bad Request content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Remove an Entry from a Radar List tags: - radar components: schemas: RadarStandaloneResponse: type: object properties: verdict: type: string enum: - allow - block - challenge description: The verdict of the risk assessment. example: block reason: type: string description: A human-readable reason for the verdict. example: Detected enabled Radar control attempt_id: type: string description: Unique identifier of the authentication attempt. example: radar_att_01HZBC6N1EB1ZY7KG32X control: type: string enum: - bot_detection - brute_force_attack - credential_stuffing - domain_sign_up_rate_limit - ip_sign_up_rate_limit - impossible_travel - repeat_sign_up - stale_account - unrecognized_device - restriction description: The Radar control that triggered the verdict. Only present if the verdict is `block` or `challenge`. example: bot_detection blocklist_type: type: string enum: - ip_address - domain - email - device - user_agent - device_fingerprint - country description: The type of blocklist entry that triggered the verdict. Only present if the control is `restriction`. example: ip_address required: - verdict - reason - attempt_id RadarListEntryAlreadyPresentResponse: type: object properties: message: type: string description: A message indicating the entry already exists. example: Entry already present in list required: - message securitySchemes: bearer: scheme: bearer bearerFormat: JWT type: http description: 'Your WorkOS API key prefixed with `sk_`. Pass it as a Bearer token: `Authorization: Bearer sk_example_123456789`.' access_token: scheme: bearer bearerFormat: JWT type: http description: An SSO access token returned from the Get a Profile and Token endpoint.