# Introspect a Basic token

`POST /core/v1/basic/introspect`

Endpoints:

- `https://api.test.neobits.ai/core/v1/basic/introspect`
- `https://api.prod.neobits.ai/core/v1/basic/introspect`

Authentication: one of the following alternatives:

- `basic`

- `basic`: Basic authentication, base64 encoded username:password.

Determines the state and validity of a Basic token

## Request body

Required: yes

Content type: `application/x-www-form-urlencoded`

```json
{
  "type": "object",
  "title": "BasicTokenIntrospectRequest",
  "required": [
    "token"
  ],
  "properties": {
    "token": {
      "type": "string",
      "description": "The Basic token to introspect"
    },
    "token_type_hint": {
      "type": "string",
      "description": "Optional hint about the token type. Accepted and ignored (RFC 7662 §2.1)"
    }
  }
}
```

## Responses

### 200 Token introspection response

Content type: `application/json`

```json
{
  "oneOf": [
    {
      "type": "object",
      "title": "ScopeBasedClient",
      "properties": {
        "active": {
          "type": "boolean",
          "description": "Whether the client is active"
        },
        "scope": {
          "type": "string",
          "description": "Scopes associated with the client"
        },
        "sub": {
          "type": "string",
          "description": "Subject of the token"
        },
        "account_id": {
          "type": "string",
          "format": "uuid",
          "description": "Account ID associated with the client"
        }
      }
    },
    {
      "type": "object",
      "title": "RoleBasedClient",
      "properties": {
        "active": {
          "type": "boolean",
          "description": "Whether the client is active"
        },
        "role": {
          "type": "string",
          "description": "Role associated with the client"
        },
        "sub": {
          "type": "string",
          "description": "Subject of the token"
        },
        "account_id": {
          "type": "string",
          "format": "uuid",
          "description": "Account ID associated with the client"
        }
      }
    },
    {
      "type": "object",
      "title": "InactiveToken",
      "description": "Unknown, invalid, expired or disabled credentials (RFC 7662 §2.2)",
      "required": [
        "active"
      ],
      "properties": {
        "active": {
          "type": "boolean",
          "enum": [
            false
          ]
        }
      }
    }
  ]
}
```

### 400 OAuth 2.0 Bad Request

Response headers and links:

```json
{
  "headers": {
    "Content-Type": {
      "description": "The content type of the response.",
      "example": "application/json; charset=utf-8",
      "schema": {
        "type": "string",
        "enum": [
          "application/json; charset=utf-8"
        ]
      }
    },
    "X-Request-ID": {
      "description": "UUID generated on each request. Provide this id to customer support if an error occurs.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "example": "0679c533-5061-496e-8dc5-df786f04a209"
      }
    }
  }
}
```

Content type: `application/json`

```json
{
  "title": "OAuth2BadRequestResponse",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "A single ASCII error code",
      "enum": [
        "invalid_request",
        "invalid_client",
        "invalid_grant",
        "unauthorized_client",
        "unsupported_grant_type",
        "invalid_scope"
      ],
      "example": "invalid_request"
    },
    "error_code": {
      "type": "integer",
      "description": "Numeric error code for programmatic handling",
      "example": 400
    },
    "error_uri": {
      "type": "string",
      "format": "uri",
      "description": "A URI identifying a human-readable web page with information about the error",
      "example": "https://docs.neobits.ai"
    },
    "error_description": {
      "type": "string",
      "description": "Human-readable ASCII text providing additional information",
      "example": "The request is missing a required parameter."
    },
    "error_timestamp": {
      "type": "string",
      "format": "date-time",
      "description": "The timestamp when the error occurred",
      "example": "2025-06-25T15:29:49.992Z"
    }
  },
  "required": [
    "error"
  ]
}
```

### 401 OAuth 2.0 Unauthorized

Response headers and links:

```json
{
  "headers": {
    "Content-Type": {
      "description": "The content type of the response.",
      "example": "application/json; charset=utf-8",
      "schema": {
        "type": "string",
        "enum": [
          "application/json; charset=utf-8"
        ]
      }
    },
    "X-Request-ID": {
      "description": "UUID generated on each request. Provide this id to customer support if an error occurs.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "example": "0679c533-5061-496e-8dc5-df786f04a209"
      }
    }
  }
}
```

Content type: `application/json`

```json
{
  "title": "OAuth2UnauthorizedResponse",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "A single ASCII error code",
      "enum": [
        "invalid_client"
      ],
      "example": "invalid_client"
    },
    "error_code": {
      "type": "integer",
      "description": "Numeric error code for programmatic handling",
      "example": 401
    },
    "error_uri": {
      "type": "string",
      "format": "uri",
      "description": "A URI identifying a human-readable web page with information about the error",
      "example": "https://docs.neobits.ai"
    },
    "error_description": {
      "type": "string",
      "description": "Human-readable ASCII text providing additional information",
      "example": "Client authentication failed."
    },
    "error_timestamp": {
      "type": "string",
      "format": "date-time",
      "description": "The timestamp when the error occurred",
      "example": "2025-06-25T15:29:49.992Z"
    }
  },
  "required": [
    "error"
  ]
}
```

### 429 OAuth 2.0 Too Many Requests. When the rate limit rejects a request, the response carries `Retry-After` and no `error_timestamp` or `X-Request-ID`, as the request never reached the API.

Response headers and links:

```json
{
  "headers": {
    "Content-Type": {
      "description": "The content type of the response.",
      "example": "application/json; charset=utf-8",
      "schema": {
        "type": "string",
        "enum": [
          "application/json; charset=utf-8"
        ]
      }
    },
    "Retry-After": {
      "description": "Seconds to wait before retrying. Sent when the rate limit rejects a request.",
      "schema": {
        "type": "integer",
        "example": 60
      }
    },
    "X-Request-ID": {
      "description": "UUID generated on each request. Provide this id to customer support if an error occurs.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "example": "0679c533-5061-496e-8dc5-df786f04a209"
      }
    }
  }
}
```

Content type: `application/json`

```json
{
  "title": "OAuth2TooManyRequestsResponse",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "A single ASCII error code",
      "enum": [
        "too_many_requests"
      ],
      "example": "too_many_requests"
    },
    "error_code": {
      "type": "string",
      "description": "Error code for programmatic handling, in the format HTTP_STATUS-SEQUENCE",
      "example": "429-000"
    },
    "error_uri": {
      "type": "string",
      "format": "uri",
      "description": "A URI identifying a human-readable web page with information about the error",
      "example": "https://docs.neobits.ai/api-reference/errors"
    },
    "error_description": {
      "type": "string",
      "description": "Human-readable ASCII text providing additional information",
      "example": "Too many requests. Please try again later."
    },
    "error_timestamp": {
      "type": "string",
      "format": "date-time",
      "description": "The timestamp when the error occurred",
      "example": "2025-06-25T15:29:49.992Z"
    }
  },
  "required": [
    "error"
  ]
}
```

### 500 OAuth 2.0 Internal Server Error

Response headers and links:

```json
{
  "headers": {
    "Content-Type": {
      "description": "The content type of the response.",
      "example": "application/json; charset=utf-8",
      "schema": {
        "type": "string",
        "enum": [
          "application/json; charset=utf-8"
        ]
      }
    },
    "X-Request-ID": {
      "description": "UUID generated on each request. Provide this id to customer support if an error occurs.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "example": "0679c533-5061-496e-8dc5-df786f04a209"
      }
    }
  }
}
```

Content type: `application/json`

```json
{
  "title": "OAuth2InternalServerErrorResponse",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "A single ASCII error code",
      "enum": [
        "server_error"
      ],
      "example": "server_error"
    },
    "error_code": {
      "type": "integer",
      "description": "Numeric error code for programmatic handling",
      "example": 500
    },
    "error_uri": {
      "type": "string",
      "format": "uri",
      "description": "A URI identifying a human-readable web page with information about the error",
      "example": "https://docs.neobits.ai"
    },
    "error_description": {
      "type": "string",
      "description": "Human-readable ASCII text providing additional information",
      "example": "The authorization server encountered an unexpected condition."
    },
    "error_timestamp": {
      "type": "string",
      "format": "date-time",
      "description": "The timestamp when the error occurred",
      "example": "2025-06-25T15:29:49.992Z"
    }
  },
  "required": [
    "error"
  ]
}
```

### 503 OAuth 2.0 Service Unavailable

Response headers and links:

```json
{
  "headers": {
    "Content-Type": {
      "description": "The content type of the response.",
      "example": "application/json; charset=utf-8",
      "schema": {
        "type": "string",
        "enum": [
          "application/json; charset=utf-8"
        ]
      }
    },
    "X-Request-ID": {
      "description": "UUID generated on each request. Provide this id to customer support if an error occurs.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "example": "0679c533-5061-496e-8dc5-df786f04a209"
      }
    }
  }
}
```

Content type: `application/json`

```json
{
  "title": "OAuth2ServiceUnavailableResponse",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "A single ASCII error code",
      "enum": [
        "temporarily_unavailable"
      ],
      "example": "temporarily_unavailable"
    },
    "error_code": {
      "type": "integer",
      "description": "Numeric error code for programmatic handling",
      "example": 503
    },
    "error_uri": {
      "type": "string",
      "format": "uri",
      "description": "A URI identifying a human-readable web page with information about the error",
      "example": "https://docs.neobits.ai"
    },
    "error_description": {
      "type": "string",
      "description": "Human-readable ASCII text providing additional information",
      "example": "The authorization server is currently unable to handle the request."
    },
    "error_timestamp": {
      "type": "string",
      "format": "date-time",
      "description": "The timestamp when the error occurred",
      "example": "2025-06-25T15:29:49.992Z"
    }
  },
  "required": [
    "error"
  ]
}
```

### 504 OAuth 2.0 Gateway Timeout

Response headers and links:

```json
{
  "headers": {
    "Content-Type": {
      "description": "The content type of the response.",
      "example": "application/json; charset=utf-8",
      "schema": {
        "type": "string",
        "enum": [
          "application/json; charset=utf-8"
        ]
      }
    },
    "X-Request-ID": {
      "description": "UUID generated on each request. Provide this id to customer support if an error occurs.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "example": "0679c533-5061-496e-8dc5-df786f04a209"
      }
    }
  }
}
```

Content type: `application/json`

```json
{
  "title": "OAuth2TimeoutResponse",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "A single ASCII error code",
      "enum": [
        "temporarily_unavailable"
      ],
      "example": "temporarily_unavailable"
    },
    "error_code": {
      "type": "integer",
      "description": "Numeric error code for programmatic handling",
      "example": 504
    },
    "error_uri": {
      "type": "string",
      "format": "uri",
      "description": "A URI identifying a human-readable web page with information about the error",
      "example": "https://docs.neobits.ai"
    },
    "error_description": {
      "type": "string",
      "description": "Human-readable ASCII text providing additional information",
      "example": "The authorization server did not receive a timely response."
    },
    "error_timestamp": {
      "type": "string",
      "format": "date-time",
      "description": "The timestamp when the error occurred",
      "example": "2025-06-25T15:29:49.992Z"
    }
  },
  "required": [
    "error"
  ]
}
```