# Authorization Request

<EndpointPage
  breadcrumbs={[
    { label: "REST APIs", href: "/rest-api/rest-api" },
    { label: "Common", href: "/rest-api/rest-api#common" },
    { label: "OAuth", href: "/rest-api/common/oauth" },
    { label: "Authorization Request" },
  ]}
  title="Authorization Request"
  method="GET"
  url="https://exchange.gemini.com/auth"
  description="The OAuth 2.0 authorization code grant flow involves the user being directed to an authorization server which returns an authorization code that may then be exchanged for access and refresh tokens. Access tokens are short-lived (24 hour expiration) and are used as authentication against Gemini APIs, while refresh tokens never expire and are used to regenerate access tokens. Users should first be redirected to Gemini to authorize access to your application. The user will be prompted to login using a Gemini OAuth window."
  example={{
    request: {
      method: "GET",
      url: "https://exchange.gemini.com/auth?client_id=my_id&response_type=code&redirect_uri=www.example.com/redirect&state=82350325&scope=balances:read,orders:create",
      headers: [],
    },
  }}
  sections={[
    {
      heading: "URL Parameters",
      children: (
        <ParamList params={[
          {
            name: "client_id",
            type: "string",
            required: true,
            description: <>Unique ID of your application. This is provided in your <a href="https://exchange.gemini.com/settings/api" style={{ color: "inherit", textDecorationLine: "underline" }}>API settings</a>.</>,
          },
          {
            name: "response_type",
            type: "string",
            required: true,
            description: 'The literal string "code".',
            example: "code",
          },
          {
            name: "redirect_uri",
            type: "string",
            required: true,
            description: "The URL users should be returned to after they authorize. This URL must be included in your list of approved redirect URIs in your app registration.",
          },
          {
            name: "state",
            type: "string",
            required: true,
            description: "A random string that will be returned to you in the response. You should verify this matches the value you sent before trusting the response.",
          },
          {
            name: "scope",
            type: "string",
            required: true,
            description: <>A comma-separated list of <a href="/authentication/oauth#oauth-scopes" style={{ color: "inherit", textDecorationLine: "underline" }}>OAuth scopes</a> corresponding to the access you are requesting. These scopes must be included in your list of scopes in your app registration.</>,
          },
        ]} />
      ),
    },
    {
      heading: "Responses",
      children: (
        <ResponsesSection tabs={[
          {
            code: "302",
            description: "Redirect to redirect_uri with authorization code and state",
            params: [
              { name: "code", type: "string", description: "A temporary authorization code to be exchanged for access and refresh tokens." },
              { name: "state", type: "string", description: "The state value you provided in the request. Verify this matches before trusting the response." },
            ],
            example: `https://www.example.com/redirect?code=90123465-86ee-44ef-b4e3-835cc89bc8a3&state=82350325`,
          },
          { code: "400", description: "Bad request - malformed request or invalid parameters", params: [{ name: "result", type: "string", description: "Error" }, { name: "reason", type: "string", description: "A short description" }, { name: "message", type: "string", description: "Detailed error message" }], example: `{\n  "result": "error",\n  "reason": "InvalidSignature",\n  "message": "Invalid signature for this request"\n}` },
          { code: "401", description: "Unauthorized - missing or invalid authentication", params: [{ name: "result", type: "string", description: "Error" }, { name: "reason", type: "string", description: "A short description" }, { name: "message", type: "string", description: "Detailed error message" }], example: `{\n  "result": "error",\n  "reason": "MissingApikeyHeader",\n  "message": "Must provide 'X-GEMINI-APIKEY' header"\n}` },
          { code: "403", description: "API key fails IP filtering check", params: [{ name: "result", type: "string", description: "Error" }, { name: "reason", type: "string", description: "A short description" }, { name: "message", type: "string", description: "Detailed error message" }], example: `{\n  "result": "error",\n  "reason": "ApiKeyIpFilteringFailure",\n  "message": "ApiKey fails IP Filtering Check for some accounts"\n}` },
          { code: "404", description: "Resource not found", params: [{ name: "result", type: "string", description: "Error" }, { name: "reason", type: "string", description: "A short description" }, { name: "message", type: "string", description: "Detailed error message" }], example: `{\n  "result": "error",\n  "reason": "EndpointNotFound",\n  "message": "API entry point not found"\n}` },
          { code: "429", description: "Too many requests - you have exceeded the rate limit", params: [{ name: "result", type: "string", description: "Error" }, { name: "reason", type: "string", description: "A short description" }, { name: "message", type: "string", description: "Detailed error message" }], example: `{\n  "result": "error",\n  "reason": "Too Many Requests",\n  "message": "Too Many Requests"\n}` },
          { code: "500", description: "Internal server error", params: [{ name: "result", type: "string", description: "Error" }, { name: "reason", type: "string", description: "A short description" }, { name: "message", type: "string", description: "Detailed error message" }], example: `{\n  "result": "error",\n  "reason": "Internal Server Error",\n  "message": "Unexpected server error occurred."\n}` },
        ]} />
      ),
    },
  ]}
/>

<PageNavigation
  prev={{ label: "OAuth", href: "/rest-api/common/oauth" }}
  next={{ label: "Get Access Token", href: "/rest-api/common/oauth/authorization-token-request" }}
/>