# OpenID Connect Configuration

`GET /core/.well-known/openid-configuration`

Endpoints:

- `https://api.test.neobits.ai/core/.well-known/openid-configuration`
- `https://api.prod.neobits.ai/core/.well-known/openid-configuration`

Authentication: none.

Retrieves the OpenID Connect configuration metadata

## Responses

### 200 OpenID Connect configuration

Response headers and links:

```json
{
  "headers": {
    "Cache-Control": {
      "description": "The document may be cached for one hour.",
      "schema": {
        "type": "string",
        "example": "public, max-age=3600"
      }
    }
  }
}
```

Content type: `application/json`

```json
{
  "type": "object",
  "title": "OpenIdConfiguration",
  "properties": {
    "issuer": {
      "type": "string",
      "description": "The issuer identifier. Matches the `iss` claim of tokens issued by this host.",
      "example": "https://api.prod.neobits.ai/core"
    },
    "jwks_uri": {
      "type": "string",
      "description": "URL of the JSON Web Key Set",
      "example": "https://api.prod.neobits.ai/core/.well-known/jwks.json"
    },
    "token_endpoint": {
      "type": "string",
      "description": "URL of the OAuth 2.0 token endpoint",
      "example": "https://api.prod.neobits.ai/core/v1/oauth2/token"
    },
    "token_endpoint_auth_methods_supported": {
      "type": "array",
      "description": "Authentication methods supported by the token endpoint",
      "items": {
        "type": "string"
      },
      "example": [
        "client_secret_basic"
      ]
    },
    "introspection_endpoint": {
      "type": "string",
      "description": "URL of the OAuth 2.0 token introspection endpoint",
      "example": "https://api.prod.neobits.ai/core/v1/oauth2/introspect"
    },
    "introspection_endpoint_auth_methods_supported": {
      "type": "array",
      "description": "Authentication methods supported by the introspection endpoint",
      "items": {
        "type": "string"
      },
      "example": [
        "client_secret_basic"
      ]
    },
    "response_types_supported": {
      "type": "array",
      "description": "Response types supported. Empty, because this host has no authorization endpoint.",
      "items": {
        "type": "string"
      },
      "example": []
    },
    "grant_types_supported": {
      "type": "array",
      "description": "Grant types supported by the Core (Authz) server",
      "items": {
        "type": "string"
      },
      "example": [
        "client_credentials"
      ]
    },
    "scopes_supported": {
      "type": "array",
      "description": "Scopes supported by the Core (Authz) server",
      "items": {
        "type": "string"
      },
      "example": [
        "client:read",
        "client:write",
        "client:update",
        "client:delete",
        "clients:read",
        "inquiry:read",
        "inquiry:write",
        "inquiry:update",
        "inquiry:delete",
        "inquiries:read",
        "person:read"
      ]
    }
  }
}
```

### 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"
  ]
}
```

### 404 OAuth 2.0 Not Found

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": "OAuth2NotFoundResponse",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "A single ASCII error code",
      "enum": [
        "invalid_request",
        "not_found"
      ],
      "example": "not_found"
    },
    "error_code": {
      "type": "integer",
      "description": "Numeric error code for programmatic handling",
      "example": 404
    },
    "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 requested resource was not found."
    },
    "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"
  ]
}
```