GETSign-in protocolAuthentication

Complete browser sign-in

/auth/callback

Exchanges one authorisation code and sets a host-only session cookie.

Authentication does not grant every action. Company scope, roles and current record access still apply. Protected writes require CSRF verification; company writes also require recent sign-in. Read the authentication guide.

Example request

// This endpoint is part of the identity-provider protocol.
// Start at /auth/login; do not construct callback or logout tokens.
// See the request fields and protocol description below.

Request parameters

Name	Location	Requirement	Schema
`code`	query	Optional	`{"type":"string"}`
`state`	query	Optional	`{"type":"string"}`

Responses

303 See Other

{
  "Domain": {
    "schema": {
      "type": "string"
    }
  },
  "Expires": {
    "schema": {
      "type": "string"
    }
  },
  "HttpOnly": {
    "schema": {
      "type": "boolean"
    }
  },
  "Location": {
    "schema": {
      "type": "string"
    }
  },
  "MaxAge": {
    "schema": {
      "format": "int64",
      "type": "integer"
    }
  },
  "Name": {
    "schema": {
      "type": "string"
    }
  },
  "Partitioned": {
    "schema": {
      "type": "boolean"
    }
  },
  "Path": {
    "schema": {
      "type": "string"
    }
  },
  "Quoted": {
    "schema": {
      "type": "boolean"
    }
  },
  "Raw": {
    "schema": {
      "type": "string"
    }
  },
  "RawExpires": {
    "schema": {
      "type": "string"
    }
  },
  "SameSite": {
    "schema": {
      "format": "int64",
      "type": "integer"
    }
  },
  "Secure": {
    "schema": {
      "type": "boolean"
    }
  },
  "Set-Cookie": {
    "schema": {
      "type": "string"
    }
  },
  "Unparsed": {
    "schema": {
      "type": "string"
    }
  },
  "Value": {
    "schema": {
      "type": "string"
    }
  }
}

No response body declared.

default Error

application/problem+json

Schema: ErrorModel

$schema string · optional: A URL to the JSON Schema for this object.
detail string · optional: A human-readable explanation specific to this occurrence of the problem.
errors array | null · optional: Optional list of individual error details
instance string · optional: A URI reference that identifies the specific occurrence of the problem.
status integer · optional: HTTP status code
title string · optional: A short, human-readable summary of the problem type. This value should not change between occurrences of the error.
type string · optional: A URI reference to human-readable documentation for the error.

Complete schema definition

{
  "additionalProperties": false,
  "properties": {
    "$schema": {
      "description": "A URL to the JSON Schema for this object.",
      "examples": [
        "https://example.com/schemas/ErrorModel.json"
      ],
      "format": "uri",
      "readOnly": true,
      "type": "string"
    },
    "detail": {
      "description": "A human-readable explanation specific to this occurrence of the problem.",
      "examples": [
        "Property foo is required but is missing."
      ],
      "type": "string"
    },
    "errors": {
      "description": "Optional list of individual error details",
      "items": {
        "$ref": "#/components/schemas/ErrorDetail"
      },
      "type": [
        "array",
        "null"
      ]
    },
    "instance": {
      "description": "A URI reference that identifies the specific occurrence of the problem.",
      "examples": [
        "https://example.com/error-log/abc123"
      ],
      "format": "uri",
      "type": "string"
    },
    "status": {
      "description": "HTTP status code",
      "examples": [
        400
      ],
      "format": "int64",
      "type": "integer"
    },
    "title": {
      "description": "A short, human-readable summary of the problem type. This value should not change between occurrences of the error.",
      "examples": [
        "Bad Request"
      ],
      "type": "string"
    },
    "type": {
      "default": "about:blank",
      "description": "A URI reference to human-readable documentation for the error.",
      "examples": [
        "https://example.com/errors/example"
      ],
      "format": "uri",
      "type": "string"
    }
  },
  "type": "object"
}

The default error response can cover several status codes. Read error handling and retry guidance.

Referenced schemas

Expand a named definition to inspect nested fields and references. The download contains the complete OpenAPI document.

ErrorDetail

{
  "additionalProperties": false,
  "properties": {
    "location": {
      "description": "Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'",
      "type": "string"
    },
    "message": {
      "description": "Error message text",
      "type": "string"
    },
    "value": {
      "description": "The value at the given location"
    }
  },
  "type": "object"
}

ErrorModel

{
  "additionalProperties": false,
  "properties": {
    "$schema": {
      "description": "A URL to the JSON Schema for this object.",
      "examples": [
        "https://example.com/schemas/ErrorModel.json"
      ],
      "format": "uri",
      "readOnly": true,
      "type": "string"
    },
    "detail": {
      "description": "A human-readable explanation specific to this occurrence of the problem.",
      "examples": [
        "Property foo is required but is missing."
      ],
      "type": "string"
    },
    "errors": {
      "description": "Optional list of individual error details",
      "items": {
        "$ref": "#/components/schemas/ErrorDetail"
      },
      "type": [
        "array",
        "null"
      ]
    },
    "instance": {
      "description": "A URI reference that identifies the specific occurrence of the problem.",
      "examples": [
        "https://example.com/error-log/abc123"
      ],
      "format": "uri",
      "type": "string"
    },
    "status": {
      "description": "HTTP status code",
      "examples": [
        400
      ],
      "format": "int64",
      "type": "integer"
    },
    "title": {
      "description": "A short, human-readable summary of the problem type. This value should not change between occurrences of the error.",
      "examples": [
        "Bad Request"
      ],
      "type": "string"
    },
    "type": {
      "default": "about:blank",
      "description": "A URI reference to human-readable documentation for the error.",
      "examples": [
        "https://example.com/errors/example"
      ],
      "format": "uri",
      "type": "string"
    }
  },
  "type": "object"
}

Operation ID: browser-callback · Contract 0.0.0-dev