Claim GitHub installations from an OAuth code
curl --request POST \
--url https://api.runaether.dev/github/installations/claim \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"code": "<string>",
"state": "<string>"
}
'import requests
url = "https://api.runaether.dev/github/installations/claim"
payload = {
"code": "<string>",
"state": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({code: '<string>', state: '<string>'})
};
fetch('https://api.runaether.dev/github/installations/claim', 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://api.runaether.dev/github/installations/claim",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'code' => '<string>',
'state' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.runaether.dev/github/installations/claim"
payload := strings.NewReader("{\n \"code\": \"<string>\",\n \"state\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.runaether.dev/github/installations/claim")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"code\": \"<string>\",\n \"state\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.runaether.dev/github/installations/claim")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"code\": \"<string>\",\n \"state\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"kind": "unavailable"
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}GitHub
Claim GitHub installations from an OAuth code
Exchanges the OAuth code GitHub redirected back with for the caller's GitHub identity, records the GitHub App installations that identity reaches as the caller's, and returns the caller's GitHub status.
Use this tool when you need to:
- Finish connecting GitHub once the install or authorize redirect hands the caller a code and state
- Renew the caller's GitHub credential and re-sync their installations with a fresh code and state from getGithubAuthorizeUrl
Examples:
- POST /github/installations/claim {"code": "9b2f61c0d4e8a7b35c1e", "state": "MTc2MTQ3MjAwMHxEdi1CQkFFQ180SUFBUkFCRUFBQVpfLUNBQUlHYzNSeWFXNW58bP3xQ2"}
Hints:
- code and state are required non-empty strings (the schema answers 422 otherwise): code is GitHub's single-use OAuth code, and state the one getGithubInstallUrl or getGithubAuthorizeUrl signed for the caller, valid for 30 minutes.
- GitHub is read in full before anything is written. The caller's installation links then become exactly the installations GitHub lists for the code's GitHub user, links to any others are removed, and a user who reaches none still answers connected with an empty installations list.
- Returns the IntegrationStatus, kind connected, with details vendor github: identity (github_user_id, login) and installations (installation_id, account_login, account_type, connected_at, repository_administration, permissions_url), most recently connected first.
- Use getGithubAuthorizeUrl instead to mint a fresh code and state after 403 github_claim_unverified or a code GitHub refused (422), and getGithubStatus to read the connection without claiming.
- Any signed-in user, for their own account; through a platform API key pinned to an org where the caller is a viewer or billing member it is refused with 403 org_role_insufficient, and an agent host's grant with 403 agent_host_route_not_allowed.
- Refused with 403 github_claim_unverified when the state does not verify (expired, altered or not signed by Aether) or binds another user, 422 for a code GitHub does not accept (spent or expired), 409 github_identity_mismatch when Aether holds another GitHub account for the caller (disconnectGithub first), 409 without a domain code while an installation the user reaches is being uninstalled (retry in a minute), 403 for a banned account, 403 account_deleting while the caller's account is being deleted, 502 when GitHub fails to answer or lists an invalid installation, and 503 on a deployment without the GitHub App.
POST
/
github
/
installations
/
claim
Claim GitHub installations from an OAuth code
curl --request POST \
--url https://api.runaether.dev/github/installations/claim \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"code": "<string>",
"state": "<string>"
}
'import requests
url = "https://api.runaether.dev/github/installations/claim"
payload = {
"code": "<string>",
"state": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({code: '<string>', state: '<string>'})
};
fetch('https://api.runaether.dev/github/installations/claim', 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://api.runaether.dev/github/installations/claim",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'code' => '<string>',
'state' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.runaether.dev/github/installations/claim"
payload := strings.NewReader("{\n \"code\": \"<string>\",\n \"state\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.runaether.dev/github/installations/claim")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"code\": \"<string>\",\n \"state\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.runaether.dev/github/installations/claim")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"code\": \"<string>\",\n \"state\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"kind": "unavailable"
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}Authorizations
Body
application/json