Exchange a handoff code for the token - API Documentation

Exchanges the one-time handoff code from the frontend URL (?code=) for the token. A code can only be exchanged once and expires after a short time (2 minutes by default). Limited to 20 requests per minute per IP. Used by the fetchdocs frontend, so the token itself never has to be part of a URL.

📤 Request

Content Type: application/json

code string required

The handoff code from the frontend URL.

Example: u0Q8m3dXJ2a9...

Request Example

{
    "code": "u0Q8m3dXJ2a9..."
}
            

📥 Response

200 Success

Content Type:

data object

Object that represent the token details.

object

token string

The JWT token that is used to authenticate the user (identity) in the frontend UI.

Example: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

expires_at string date-time

The date and time when the token expires. This is also included in the JWT token itself.

Example: 2019-02-01T03:45:27+00:00

handoff_code string

One-time code that opens the frontend for this token without putting the token into a URL. It can be exchanged once (POST /v1/token/exchange) and expires after a short time (2 minutes by default).

Example: u0Q8m3dXJ2a9...

handoff_url string

The frontend URL with the handoff code. Redirect the user to this URL to open fetchdocs. Opening the frontend with ?token= keeps working.

Example: https://your-domain.fetchdocs.io?code=u0Q8m3dXJ2a9...

401 Unknown, expired or already used code

Content Type:

The error response is returned when the client is not authenticated. The client must provide a valid authentication key to access the resource.

error string

The error code is a machine readable code describing the error.

Example: API_KEY_MISSING_OR_INVALID

message string

The error message is a human readable message describing the error. It is mainly used for understanding the error by developers. It is not meant to be shown to real users.

Example: API key is missing or invalid.

suggestion string

For many errors we provide suggestions how you can resolve the error on your own.

Example: Either you didn't pass an API key or it is invalid. You can find or create a new API key in the environments section. It must be passed as X-API-Key header.

trace_id string

The trace ID is a unique identifier for the request. It is used to trace the request through the system. Please provide the trace_id when reporting an error to our support team.

Example: 1b935d50c2393af77b1dc92e675876a83f92ffd6

help string

This parameter provides a way to contact support. It is mainly used for developers. It is not meant to be shown to real users.

Example: If you need help, email [email protected] and include the following Trace-ID in your message: 1b935d50c2393af77b1dc92e675876a83f92ffd6.

422 Unprocessable Entity

Content Type:

The error response is returned when the client has provided invalid data in the request.

error string

The error code is a machine readable code describing the error.

Example: VALIDATION_ERROR

message string

The error message is a human readable message describing the error. It is mainly used for understanding the error by developers. It is not meant to be shown to real users.

Example: The identity uuid field is required. | The return url field is required.

suggestion string

For many errors we provide suggestions how you can resolve the error on your own.

Example: There might be some parameters are missing or the values of parameters you have passed are invalid. Please check the payload and make sure it conforms with the rules mentioned in API doc.

trace_id string

The trace ID is a unique identifier for the request. It is used to trace the request through the system. Please provide the trace_id when reporting an error to our support team.

Example: 1b935d50c2393af77b1dc92e675876a83f92ffd6

errors object

The errors object contains a list of fields with their corresponding error messages.

Example: { "identity_uuid": [ "The identity uuid field is required." ], "return_url": [ "The return url field is required." ] }

help string

This parameter provides a way to contact support. It is mainly used for developers. It is not meant to be shown to real users.

Example: If you need help, email [email protected] and include the following Trace-ID in your message: 1b935d50c2393af77b1dc92e675876a83f92ffd6.

Response Examples

{
  "data": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "expires_at": "2019-02-01T03:45:27+00:00",
    "handoff_code": "u0Q8m3dXJ2a9...",
    "handoff_url": "https://your-domain.fetchdocs.io?code=u0Q8m3dXJ2a9..."
  }
}
    

{ "error": "API_KEY_MISSING_OR_INVALID", "message": "API key is missing or invalid.", "suggestion": "Either you didn't pass an API key or it is invalid. You can find or create a new API key in the environments section. It must be passed as X-API-Key header.", "trace_id": "1b935d50c2393af77b1dc92e675876a83f92ffd6", "help": "If you need help, email [email protected] and include the following Trace-ID in your message: 1b935d50c2393af77b1dc92e675876a83f92ffd6." }

{ "error": "VALIDATION_ERROR", "message": "The identity uuid field is required. | The return url field is required.", "suggestion": "There might be some parameters are missing or the values of parameters you have passed are invalid. Please check the payload and make sure it conforms with the rules mentioned in API doc.", "trace_id": "1b935d50c2393af77b1dc92e675876a83f92ffd6", "errors": { "identity_uuid": [ "The identity uuid field is required." ], "return_url": [ "The return url field is required." ] }, "help": "If you need help, email [email protected] and include the following Trace-ID in your message: 1b935d50c2393af77b1dc92e675876a83f92ffd6." }

Body Parameters