Sessions

Table of Content:

Create session

This API endpoint starts a new session and sends a one-time password for verification.

Endpoint: https://apis.threatwinds.com/api/auth/v2/session

Parameters

Parameter Location Type Required Description Example
email body string Yes The email address associated with your account. This email will be used to send the verification code. “john@doe.net”
kind body string No The type of session to create. Can be “standard” or “programmatic”. Defaults to “standard”. “standard”

To create a session, use a POST request, for example:

curl -X 'POST' \
  'https://apis.threatwinds.com/api/auth/v2/session' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "john@doe.net"
}'

Returns

A successful response will return a JSON object containing session information and a verification code ID:

{
  "bearer": "<YOUR_BEARER_TOKEN>",
  "sessionID": "5f35d2c4-5633-4b16-bbf0-5ca22ef8ea2e",
  "expireAt": 1674492894,
  "ip": "1.1.1.1",
  "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36",
  "verificationCodeID": "5f35d2c4-5633-4b16-bbf0-5ca22ef8ea2e",
  "kind": "standard"
}

Note: The session is not fully active until it is verified with the verification code sent to your email. Verification codes expire after 5 minutes. A maximum of 3 attempts are allowed per code before it is invalidated.

Check session

This API endpoint checks a user session and returns privileges.

Endpoint: https://apis.threatwinds.com/api/auth/v2/session

Parameters

Parameter Location Type Required Description
Authorization header string Yes Bearer token from an active session.

To check a session, use a GET request, for example:

curl -X 'GET' \
  'https://apis.threatwinds.com/api/auth/v2/session' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>'

Returns

A successful response will return a JSON object containing information about the session and user privileges:

{
  "sessionID": "5f35d2c4-5633-4b16-bbf0-5ca22ef8ea2e",
  "userID": "5f35d2c4-5633-4b16-bbf0-5ca22ef8ea2e",
  "alias": "johny",
  "fullName": "John Doe",
  "expireAt": 1674492894,
  "ip": "1.1.1.1",
  "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36",
  "verified": true,
  "kind": "standard",
  "roles": ["user", "users_admin"],
  "groups": ["public"]
}

Note: The verified field indicates whether the user’s identity has been verified. This can happen through document and selfie verification, admin override (PUT /admin/user/{id}/verify), or automatic verification for partner-created users. This is separate from session verification (which is required to use the session). ```

Close session

This API endpoint closes a session. You can only close sessions belonging to your own user account. To close any session regardless of owner, use the admin endpoint DELETE /admin/session/{id}.

Endpoint: https://apis.threatwinds.com/api/auth/v2/session/{id}

Parameters

Parameter Location Type Required Description Example
Authorization header string Yes Bearer token from an active session.  
id path string Yes The ID of the session to close. 5f35d2c4-5633-4b16-bbf0-5ca22ef8ea2e

To close a session, use a DELETE request, for example:

curl -X 'DELETE' \
  'https://apis.threatwinds.com/api/auth/v2/session/5f35d2c4-5633-4b16-bbf0-5ca22ef8ea2e' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>'

Returns

A successful response will return a JSON object with a success message:

{
  "message": "acknowledged"
}

Extend session

This API endpoint extends the current session’s expiration time.

Endpoint: https://apis.threatwinds.com/api/auth/v2/session/extend

Parameters

Parameter Location Type Required Description
Authorization header string Yes Bearer token from an active session.

To extend a session, use a PUT request, for example:

curl -X 'PUT' \
  'https://apis.threatwinds.com/api/auth/v2/session/extend' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>'

Returns

A successful response will return a JSON object with a success message:

{
  "message": "acknowledged"
}

Note: Sessions have automatic sliding expiry — every authenticated request extends the session’s expiration time. This means the extend endpoint is typically unnecessary in normal usage; a session only expires if the user is idle for the full session duration window.

Verify session

This API endpoint verifies a session using the verification code sent during session creation.

Endpoint: https://apis.threatwinds.com/api/auth/v2/session/verification

Parameters

Parameter Location Type Required Description Example
verificationCodeID body string Yes The verification code ID received when creating the session. “5f35d2c4-5633-4b16-bbf0-5ca22ef8ea2e”
code body string Yes The verification code sent to your email. “654321”

This endpoint does not require authentication. Only the verification code and ID are needed.

Note: Verification codes expire after 5 minutes. A maximum of 3 attempts are allowed per code before it is invalidated. If the code expires or attempts are exhausted, create a new session to receive a fresh code.

To verify a session, use a PUT request, for example:

curl -X 'PUT' \
  'https://apis.threatwinds.com/api/auth/v2/session/verification' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "verificationCodeID": "5f35d2c4-5633-4b16-bbf0-5ca22ef8ea2e",
  "code": "654321"
}'

Returns

A successful response will return a JSON object with a success message:

{
  "message": "acknowledged"
}

Get sessions

This API endpoint gets all active sessions for the current user.

Endpoint: https://apis.threatwinds.com/api/auth/v2/sessions

Parameters

Parameter Location Type Required Description
Authorization header string Yes Bearer token from an active session.

To get all sessions, use a GET request, for example:

curl -X 'GET' \
  'https://apis.threatwinds.com/api/auth/v2/sessions' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>'

Returns

A successful response will return a JSON object containing an array of active sessions:

{
  "sessions": [
    {
      "sessionID": "5f35d2c4-5633-4b16-bbf0-5ca22ef8ea2e",
      "ip": "1.1.1.1",
      "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36",
      "expireAt": 1674492894,
      "current": true,
      "kind": "standard"
    },
    {
      "sessionID": "6a2b4c5d-6e7f-8g9h-0i1j-2k3l4m5n6o7p",
      "ip": "2.2.2.2",
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.114 Safari/537.36",
      "expireAt": 1674492894,
      "current": false,
      "kind": "standard"
    }
  ]
}

Error Response Headers

For responses with status codes other than 200 and 202, the following headers are included:

Header Description
x-error Human-readable error message describing what went wrong
x-error-id Unique identifier for error tracking and support

Error Codes

Status Code Description Possible Cause
400 Bad Request Invalid request parameters or malformed JSON
401 Unauthorized Missing or invalid authentication credentials
403 Forbidden Authenticated user lacks permission for this operation
404 Not Found The requested resource does not exist
500 Internal Server Error Server-side error; please contact support if persistent