Complete an OAuth Login

GET

auth

oauth

{provider}

callback

OAuth callback (provider redirects here)

curl --request GET \
  --url https://billing.example.com/auth/oauth/{provider}/callback \
  --header 'Authorization: <api-key>'

const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

fetch('https://billing.example.com/auth/oauth/{provider}/callback', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://billing.example.com/auth/oauth/{provider}/callback",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.example.com/auth/oauth/{provider}/callback"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://billing.example.com/auth/oauth/{provider}/callback")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "error": {
    "code": "validation_failed",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "validation_failed",
    "message": "<string>"
  }
}

The provider redirects the browser here after the user consents. The server validates the returned state against the recurso_oauth_state cookie set by GET /auth/oauth/{provider}/start (constant-time compare), exchanges code for a token using the bound PKCE verifier, fetches the user’s profile, and requires a verified email (Google: email_verified is true; GitHub: a primary, verified email). It then finds or creates the account:

An existing linked identity logs in.
An existing user with the same verified email is linked to the new identity and logged in.
A brand-new email creates a tenant and its owner user, the same as POST /auth/register.

On success the server sets the recurso_session cookie — identical to a password login — and 302s to the dashboard root. On any failure other than a state mismatch it 302s to {DASHBOARD_URL}/login?error=oauth; the redirect target is always the configured dashboard URL, never a caller-supplied one. The state cookie is cleared whichever way the attempt ends, so each start is single-use. You do not call this endpoint yourself — register it as the provider’s redirect URI (https://api.recurso.dev/auth/oauth/{provider}/callback).

Path Parameters

Parameter	Type	Required	Description
`provider`	string	Yes	The provider completing the login: `google` or `github`. Must match the provider bound into the state cookie.

Query Parameters

Parameter	Type	Required	Description
`code`	string	No	The authorization code issued by the provider. Missing code redirects to the login error page.
`state`	string	No	The CSRF state echoed by the provider. Must equal the value bound into the state cookie.

Example Request

curl -i "https://api.recurso.dev/auth/oauth/google/callback?code=4%2F0AbCdEf...&state=Kx9v...Qm" \
  -b "recurso_oauth_state=eyJwIjoiZ29vZ2xlIi...aWQ.7hQ...Lw"

Example Response

There is no response body. A successful login answers 302 Found with the session cookie:

HTTP/1.1 302 Found
Location: https://app.recurso.dev/
Set-Cookie: recurso_session=...; Path=/; HttpOnly; Secure; SameSite=Lax
Set-Cookie: recurso_oauth_state=; Path=/auth/oauth; Max-Age=0; HttpOnly; Secure; SameSite=Lax

A failed exchange, an unverified email, an expired (older than 10 minutes) or missing state cookie, or a login error all answer 302 Found with Location: https://app.recurso.dev/login?error=oauth.

Errors

Status	Code	When	Fix
`403`	`forbidden`	The `state` query value does not match the state bound in the cookie.	Start the flow again from `GET /auth/oauth/{provider}/start`; do not reuse an old authorize URL.
`404`	`not_found`	`provider` is unknown or not configured.	Only route callbacks for providers listed as `enabled` by `GET /auth/oauth/providers`.

Errors use the standard envelope — see Errors.

Authorizations

Authorization

string

header

required

Path Parameters

provider

enum<string>

required

Available options:

google,

github

Query Parameters

code

string

state

string

Response

Redirect to the dashboard on success, or to the login error page on failure. Sets the session cookie on success.

OAuth callback (provider redirects here)

curl --request GET \
  --url https://billing.example.com/auth/oauth/{provider}/callback \
  --header 'Authorization: <api-key>'

const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

fetch('https://billing.example.com/auth/oauth/{provider}/callback', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://billing.example.com/auth/oauth/{provider}/callback",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.example.com/auth/oauth/{provider}/callback"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://billing.example.com/auth/oauth/{provider}/callback")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "error": {
    "code": "validation_failed",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "validation_failed",
    "message": "<string>"
  }
}

Getting Started

Core

Billing & Invoicing

Revenue & Finance

Growth & Recovery

Compliance (India)

Platform

Customer Portal API

Complete an OAuth Login

Path Parameters

Query Parameters

Example Request

Example Response

Errors

Authorizations

Path Parameters

Query Parameters

Response

​Path Parameters

​Query Parameters

​Example Request

​Example Response

​Errors

Authorizations

Path Parameters

Query Parameters

Response

Path Parameters

Query Parameters

Example Request

Example Response

Errors