# Inspect your API identity

GET /api/auth/session

**Required scope:** `read`. **Roles:** Reviewer, Owner, Admin.

Returns the effective member role and API-key scopes. Internal environment names retain dev; this is the main Math deployment.

Examples use synthetic data. This is a complete OpenAPI document for this operation, including required schemas.

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Inspect your API identity",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://math-api.qmindlabs.ai",
      "description": "Main Math API"
    }
  ],
  "security": [
    {
      "ApiKey": []
    }
  ],
  "paths": {
    "/api/auth/session": {
      "get": {
        "tags": [
          "Authentication"
        ],
        "summary": "Inspect your API identity",
        "operationId": "get__api_auth_session",
        "description": "**Required scope:** `read`. **Roles:** Reviewer, Owner, Admin.\n\nReturns the effective member role and API-key scopes. Internal environment names retain dev; this is the main Math deployment.",
        "x-required-scopes": [
          "read"
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Successful response",
            "headers": {
              "x-request-id": {
                "description": "Server-generated identifier for tracing this request.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Session"
                },
                "example": {
                  "schema_version": "dashboard-auth-v2",
                  "admin_provisioned": true,
                  "user": {
                    "id": 42,
                    "username": "example_member",
                    "email": null,
                    "email_verified": false,
                    "display_name": "Example member",
                    "role": "REVIEWER",
                    "is_admin": false,
                    "is_primary_admin": false,
                    "enabled": true,
                    "must_change_password": false,
                    "last_login_at": null,
                    "authenticated_role": "REVIEWER",
                    "active_role": "REVIEWER",
                    "can_switch_role": false,
                    "viewing_user": null,
                    "identity_id": "example-identity",
                    "api_key": {
                      "id": "bbbbbbbbbbbbbbbbbbbbbbbb",
                      "name": "example",
                      "scopes": [
                        "read"
                      ]
                    },
                    "workspace": {
                      "id": "ws_math",
                      "slug": "math",
                      "label": "Math",
                      "environment": "dev"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "headers": {
              "x-request-id": {
                "description": "Server-generated identifier for tracing this request.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "invalid_request",
                  "message": "Invalid input"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired or revoked API key",
            "headers": {
              "x-request-id": {
                "description": "Server-generated identifier for tracing this request.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "invalid_api_key",
                  "message": "Missing, invalid, expired or revoked API key"
                }
              }
            }
          },
          "403": {
            "description": "Role, scope, account or origin does not permit this operation",
            "headers": {
              "x-request-id": {
                "description": "Server-generated identifier for tracing this request.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "api_key_scope_required",
                  "message": "Role, scope, account or origin does not permit this operation"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable or outside your permitted tasks",
            "headers": {
              "x-request-id": {
                "description": "Server-generated identifier for tracing this request.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "not_found",
                  "message": "Resource unavailable or outside your permitted tasks"
                }
              }
            }
          },
          "405": {
            "description": "HTTP method is not supported",
            "headers": {
              "x-request-id": {
                "description": "Server-generated identifier for tracing this request.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "method_not_allowed",
                  "message": "HTTP method is not supported"
                }
              }
            }
          },
          "409": {
            "description": "Stale version, invalid workflow transition or changed evidence; read the latest state before retrying",
            "headers": {
              "x-request-id": {
                "description": "Server-generated identifier for tracing this request.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "math_workflow_conflict",
                  "message": "Stale version, invalid workflow transition or changed evidence; read the latest state before retrying"
                }
              }
            }
          },
          "413": {
            "description": "Request exceeds the permitted upload or JSON size",
            "headers": {
              "x-request-id": {
                "description": "Server-generated identifier for tracing this request.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "payload_too_large",
                  "message": "Request exceeds the permitted upload or JSON size"
                }
              }
            }
          },
          "415": {
            "description": "Unsupported request Content-Type",
            "headers": {
              "x-request-id": {
                "description": "Server-generated identifier for tracing this request.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "json_required",
                  "message": "Unsupported request Content-Type"
                }
              }
            }
          },
          "429": {
            "description": "600 authenticated requests per minute per key exceeded; retry next minute",
            "headers": {
              "x-request-id": {
                "description": "Server-generated identifier for tracing this request.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "api_key_rate_limited",
                  "message": "600 authenticated requests per minute per key exceeded; retry next minute"
                }
              }
            }
          },
          "503": {
            "description": "Service, storage or capacity temporarily unavailable",
            "headers": {
              "x-request-id": {
                "description": "Server-generated identifier for tracing this request.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "service_unavailable",
                  "message": "Service, storage or capacity temporarily unavailable"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "Math API key",
        "description": "Paste your issued key, without the Bearer prefix. No key is embedded in this documentation."
      }
    },
    "schemas": {
      "Session": {
        "type": "object",
        "properties": {
          "schema_version": {
            "const": "dashboard-auth-v2",
            "type": "string"
          },
          "admin_provisioned": {
            "type": "boolean"
          },
          "user": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer",
                "minimum": 1,
                "maximum": 9007199254740991,
                "example": 42
              },
              "username": {
                "type": "string",
                "example": "example_member"
              },
              "email": {
                "anyOf": [
                  {
                    "type": "string",
                    "example": "member@example.com"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "email_verified": {
                "type": "boolean",
                "example": false
              },
              "display_name": {
                "type": "string",
                "example": "Example member"
              },
              "role": {
                "type": "string",
                "enum": [
                  "REVIEWER",
                  "OWNER",
                  "ADMIN"
                ]
              },
              "is_admin": {
                "type": "boolean",
                "example": false
              },
              "is_primary_admin": {
                "type": "boolean",
                "example": false
              },
              "enabled": {
                "type": "boolean"
              },
              "must_change_password": {
                "type": "boolean",
                "const": false
              },
              "last_login_at": {
                "anyOf": [
                  {
                    "type": "string",
                    "format": "date-time",
                    "example": "2026-09-22T12:00:00.000Z"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "authenticated_role": {
                "type": "string",
                "enum": [
                  "REVIEWER",
                  "OWNER",
                  "ADMIN"
                ]
              },
              "active_role": {
                "type": "string",
                "enum": [
                  "REVIEWER",
                  "OWNER",
                  "ADMIN"
                ]
              },
              "can_switch_role": {
                "type": "boolean",
                "const": false
              },
              "viewing_user": {
                "type": "null"
              },
              "identity_id": {
                "type": "string",
                "example": "example-identity"
              },
              "api_key": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "pattern": "^[0-9a-f]{24}$",
                    "example": "bbbbbbbbbbbbbbbbbbbbbbbb"
                  },
                  "name": {
                    "type": "string"
                  },
                  "scopes": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "read",
                        "write",
                        "files:read",
                        "files:write",
                        "paths:read",
                        "keys:manage"
                      ]
                    },
                    "minItems": 1,
                    "maxItems": 6,
                    "uniqueItems": true
                  }
                },
                "required": [
                  "id",
                  "name",
                  "scopes"
                ],
                "additionalProperties": false
              },
              "workspace": {
                "type": "object",
                "properties": {
                  "id": {
                    "const": "ws_math",
                    "type": "string"
                  },
                  "slug": {
                    "const": "math",
                    "type": "string"
                  },
                  "label": {
                    "const": "Math",
                    "type": "string"
                  },
                  "environment": {
                    "const": "dev",
                    "type": "string",
                    "description": "Retained internal name of the main Math workspace."
                  }
                },
                "required": [
                  "id",
                  "slug",
                  "label",
                  "environment"
                ],
                "additionalProperties": false
              }
            },
            "required": [
              "id",
              "username",
              "email",
              "email_verified",
              "display_name",
              "role",
              "is_admin",
              "is_primary_admin",
              "enabled",
              "must_change_password",
              "last_login_at",
              "authenticated_role",
              "active_role",
              "can_switch_role",
              "viewing_user",
              "identity_id",
              "api_key",
              "workspace"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "schema_version",
          "admin_provisioned",
          "user"
        ],
        "additionalProperties": false
      },
      "Error": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "example": "api_key_scope_required"
          },
          "message": {
            "type": "string",
            "example": "This operation requires the read scope."
          }
        },
        "required": [
          "code",
          "message"
        ],
        "additionalProperties": false
      }
    }
  }
}
```