DEV Community: PIPO

Notes about Geolocation/IPGeolocation

PIPO — Sat, 01 Feb 2025 12:19:13 +0000

Notes about Geolocation

There are several providers who offer this "service"... Geolocation from an IP.

I'm gonna resume some few services, and a basic usage of them, just to help others to know how to use the IP Geolocation and what it offers.

Summary

FREE Services
- Maybe, the best, cheap, fast, most basic and reliable is my-ip.io / my-ip.io/My IP
- Additionally, we can use api-bdc.net/Reverse Geocode
- And, for more details, we can use api-bdc.net/Roaming
APIKey Services
- With subscriptions, we can use api-bdc.net/IP Geolocation FULL for full info.
- Also, we can use api-bdc.net/Reverse Geocode Client for less info.
- Another option is to use ipapi.com/Info about any IP

my-ip.io

Service BIO:

Web site: https://www.my-ip.io/
Documentation: https://www.my-ip.io/api-usage
Susbscription type: It's FREE.

FREE EndPoints

My IP

Sample Request

# PowerShell
Clear-Host;
$RootURL = "https://api.my-ip.io";
$BaseURL = "${RootURL}/v2/ip.json";

## My IP
$MyIpioInfo = IRM "${BaseURL}";
$MyIpioInfo;
$MyIpioInfo | ConvertTo-Json -Depth 9;

$MyIpioIP = $MyIpioInfo.ip;
$MyIpioIP;

Sample Response

{
    "success": true,
    "ip": "[MY_IP]",
    "type": "IPv4",
    "country": {
        "code": "[MY_COUNTRY_CODE]",
        "name": "[MY_COUNTRY_NAME]"
    },
    "region": "[MY_REGION]",
    "city": "[MY_CITY]",
    "location": {
        "lat": [MY_LATITUDE_SHORT],
        "lon": [MY_LONGITUDE_SHORT]
    },
    "timeZone": "[MY_TIMEZONE]",
    "asn": {
        "number": [MY_ASN],
        "name": "[MY_ASN_NAME]",
        "network": "[MY_ASN_NETWORK]"
    }
}

api-bdc.net / bigdatacloud.com

Service BIO:

Web site: https://www.bigdatacloud.com/
Documentation: https://www.bigdatacloud.com/free-api
Susbscription type: Allow FREE, but subject to 10.000 "queries" per month.

FREE EndPoints

Client IP

Sample Request

# PowerShell
Clear-Host;
$BaseURL = "https://api-bdc.net";

$Response = IRM "${BaseURL}/data/client-ip"
$Response;
$Response | ConvertTo-Json -Depth 9;

## My IP
$MyBDCClientIP = $Response.ipString;
$MyBDCClientIP;

Sample Response

{
    "ipString": "[MY_IP]",
    "ipType": "IPv4"
}

Client Info

Sample Request

# PowerShell
Clear-Host;
$BaseURL = "https://api-bdc.net";

$MyBDCClientInfo = IRM "${BaseURL}/data/client-info"
$MyBDCClientInfo;
$MyBDCClientInfo | ConvertTo-Json -Depth 9;

Sample Response

{
    "ipString": "[MY_IP]",
    "ipNumeric": [MY_NUMERIC_IP],
    "ipType": "IPv4",
    "isBehindProxy": false,
    "device": "Desktop",
    "os": "Windows 10",
    "userAgent": "WindowsPowerShell 5.1.22621",
    "family": "WindowsPowerShell",
    "versionMajor": "5",
    "versionMinor": "1",
    "versionPatch": "22621",
    "isSpider": false,
    "isMobile": false,
    "userAgentDisplay": "Windows 10 Desktop WindowsPowerShell 5.1.22621",
    "userAgentRaw": "Mozilla/5.0 (Windows NT; Windows NT 10.0; es-ES) WindowsPowerShell/5.1.22621.4391"
}

Reverse Geocode

Sample Request

# PowerShell
Clear-Host;
$BaseURL = "https://api-bdc.net";

$MyBDCRevGeoInfo = IRM "${BaseURL}/data/reverse-geocode-client?localityLanguage=es"
$MyBDCRevGeoInfo;
$MyBDCRevGeoInfo | ConvertTo-Json -Depth 9;

Sample Response

{
    "latitude": [MY_LATITUDE],
    "lookupSource": "ip geolocation",
    "longitude": [MY_LONGITUDE],
    "localityLanguageRequested": "[MY_COUNTRY_CODE]",
    "continent": "Europa",
    "continentCode": "EU",
    "countryName": "[MY_COUNTRY_NAME]",
    "countryCode": "[MY_COUNTRY_CODE]",
    "principalSubdivision": "[MY_REGION]",
    "principalSubdivisionCode": "[MY_REGION_CODE]",
    "city": "[MY_CITY]",
    "locality": "[MY_LOCALITY]",
    "postcode": "",
    "plusCode": "[MY_PLUS_CODE]",
    "localityInfo": {
        "administrative": [
            {
                "name": "[MY_COUNTRY_NAME]",
                "description": "pa\u00eds del suroeste de Europa",
                "isoName": "[MY_COUNTRY_ISO_NAME]",
                "order": 2,
                "adminLevel": 2,
                "isoCode": "[MY_COUNTRY_ISO_CODE]",
                "wikidataId": "[MY_WIKIDATA_ID]",
                "geonameId": [MY_GEONAME_ID]
            },
            {...},
            {...}
        ],
        "informative": [
            {
                "name": "Europa",
                "description": "continente ba\u00f1ado principalmente por el Atl\u00e1ntico",
                "isoName": "Europe",
                "order": 1,
                "isoCode": "EU",
                "wikidataId": "Q46",
                "geonameId": 6255148
            },
            {...}
        ]
    }
}

Roaming

Requires latitude and longitude.
Afortunatelly, we can get those values from the previous call.

Sample Request

# PowerShell
Clear-Host;
$BaseURL = "https://api-bdc.net";

$MyBDCRevGeoInfo = IRM "${BaseURL}/data/reverse-geocode-client"
$MyBDCLatitude = $MyBDCRevGeoInfo.latitude;
$MyBDCLongitude = $MyBDCRevGeoInfo.longitude;

$MyBDCRoamingInfo = IRM "${BaseURL}/data/am-i-roaming?latitude=${MyBDCLatitude}&longitude=${MyBDCLongitude}"
$MyBDCRoamingInfo;
$MyBDCRoamingInfo | ConvertTo-Json -Depth 9;

Sample Response

{
    "isRoaming": false
}

APIKey EndPoints

IP Geolocation FULL

Availables here: https://www.bigdatacloud.com/ip-geolocation
Requires an APIKey.

Sample Request

# PowerShell
Clear-Host;
$MyBDCAPIKey = "[MY_BDC_API_KEY]";
$RootURL = "https://api-bdc.net";
$BaseURL = "${RootURL}/data";

$MyBDCGeoLocFULL = IRM "${BaseURL}/ip-geolocation-full?key=${MyBDCAPIKey}&localityLanguage=es"
$MyBDCGeoLocFULL;
$MyBDCGeoLocFULL | ConvertTo-Json -Depth 9;

Sample Response

{
    "ip": "[MY_IP]",
    "localityLanguageRequested": "[MY_COUNTRY_CODE]",
    "isReachableGlobally": true,
    "country": {
        "isoAlpha2": "[MY_COUNTRY_ALPHA2_CODE]",
        "isoAlpha3": "[MY_COUNTRY_ALPHA3_CODE]",
        "m49Code": [MY_COUNTRY_M49_CODE],
        "name": "[MY_COUNTRY_NAME]",
        "isoName": "[MY_COUNTRY_ISO_NAME]",
        "isoNameFull": "[MY_COUNTRY_ISO_FULL_NAME]",
        "isoAdminLanguages": [
            {
                "isoAlpha3": "[MY_LANGUAGE_ALPHA3_CODE]",
                "isoAlpha2": "[MY_LANGUAGE_ALPHA2_CODE]",
                "isoName": "[MY_LANGUAGE_ISO_NAME]",
                "nativeName": "[MY_LANGUAGE_NAME]"
            }
        ],
        "unRegion": "Europe and Northern America/Europe/Southern Europe",
        "currency": {
            "numericCode": 978,
            "code": "EUR",
            "name": "Euro",
            "minorUnits": 2
        },
        "wbRegion": {
            "id": "ECS",
            "iso2Code": "Z7",
            "value": "Europe & Central Asia"
        },
        "wbIncomeLevel": {
            "id": "HIC",
            "iso2Code": "XD",
            "value": "High income"
        },
        "callingCode": "[MY_COUNTRY_CALLING_CODE]",
        "countryFlagEmoji": "[MY_COUNTRY_FLAG_EMOJI]",
        "wikidataId": "[MY_WIKIDATA]",
        "geonameId": [MY_GEONAME_ID],
        "isIndependent": true
    },
    "location": {
        "principalSubdivision": "[MY_REGION]",
        "isoPrincipalSubdivision": "[MY_REGION_ISO]",
        "isoPrincipalSubdivisionCode": "[MY_REGION_ISO_CODE]",
        "continent": "Europa",
        "continentCode": "EU",
        "city": "[MY_CITY]",
        "localityName": "[MY_LOCALITY]",
        "postcode": "",
        "latitude": [MY_LATITUDE_SHORT],
        "longitude": [MY_LONGITUDE_SHORT],
        "plusCode": "[MY_PLUS_CODE]",
        "timeZone": {
            "ianaTimeId": "[MY_TIMEZONE]",
            "displayName": "[MY_TIMEZONE_NAME]",
            "effectiveTimeZoneFull": "Central European Standard Time",
            "effectiveTimeZoneShort": "CET",
            "utcOffsetSeconds": 3600,
            "utcOffset": "+01",
            "isDaylightSavingTime": false,
            "localTime": "2025-02-01T10:21:36.9293308"
        },
        "localityInfo": {
            "administrative": [
                {
                    "name": "[MY_COUNTRY_NAME]",
                    "description": "pa\u00eds del suroeste de Europa",
                    "isoName": "[MY_COUNTRY_ISO_NAME]",
                    "order": 2,
                    "adminLevel": 2,
                    "isoCode": "[MY_COUNTRY_CODE]",
                    "wikidataId": "Q29",
                    "geonameId": 2510769
                },
                {...},
                {...}
            ],
            "informative": [
                {
                    "name": "Europa",
                    "description": "continente ba\u00f1ado principalmente por el Atl\u00e1ntico",
                    "isoName": "Europe",
                    "order": 1,
                    "isoCode": "EU",
                    "wikidataId": "Q46",
                    "geonameId": 6255148
                },
                {...},
                {...}
            ]
        }
    },
    "lastUpdated": "2025-02-01T04:44:13.6068279Z",
    "network": {
        "registry": "RIPE",
        "registryStatus": "assigned",
        "registeredCountry": "[MY_COUNTRY_CODE]",
        "registeredCountryName": "[MY_COUNTRY_NAME]",
        "organisation": "[MY_CARRIER]",
        "isReachableGlobally": true,
        "isBogon": false,
        "bgpPrefix": "[MY_CARRIER_PREFIX]",
        "bgpPrefixNetworkAddress": "[MY_CARRIER_NET_ADDRESS]",
        "bgpPrefixLastAddress": "[MY_CARRIER_LAST_ADDRESS]",
        "totalAddresses": 4096,
        "carriers": [
            {...info about carriers...}
        ],
        "viaCarriers": [
            {...info about via carrier...},
            {...info about via carrier...},
            {...info about via carrier...}
        ]
    },
    "confidence": "high",
    "confidenceArea": [ // Array of points delimiting an area
        {
            "latitude": [LATITUDE],
            "longitude": [LONGITUDE]
        }
    ],
    "securityThreat": "unknown",
    "hazardReport": {
        "isKnownAsTorServer": false,
        "isKnownAsVpn": false,
        "isKnownAsProxy": false,
        "isSpamhausDrop": false,
        "isSpamhausEdrop": false,
        "isSpamhausAsnDrop": false,
        "isBlacklistedUceprotect": false,
        "isBlacklistedBlocklistDe": false,
        "isKnownAsMailServer": false,
        "isKnownAsPublicRouter": false,
        "isBogon": false,
        "isUnreachable": false,
        "hostingLikelihood": 0,
        "isHostingAsn": false,
        "isCellular": false,
        "iCloudPrivateRelay": false
    }
}

Reverse Geocode Client

Availables here: https://www.bigdatacloud.com/reverse-geocoding
Requires an APIKey, the latitude and the longitude.
Afortunatelly, we can get those values from the previous call.

Sample Request

# PowerShell
Clear-Host;
$MyBDCAPIKey = "[MY_BDC_API_KEY]";
$RootURL = "https://api-bdc.net";
$BaseURL = "${RootURL}/data";

$MyBDCRevGeoClientInfo = IRM "${BaseURL}/reverse-geocode-with-timezone?key=${MyBDCAPIKey}&latitude=${MyBDCLatitude}&longitude=${MyBDCLongitude}&localityLanguage=es"
$MyBDCRevGeoClientInfo;
$MyBDCRevGeoClientInfo | ConvertTo-Json -Depth 9;

Sample Response

{
    "latitude": [MY_LATITUDE],
    "longitude": [MY_LONGITUDE],
    "localityLanguageRequested": "[MY_COUNTRY_CODE]",
    "continent": "Europa",
    "continentCode": "EU",
    "countryName": "[MY_COUNTRY_NAME]",
    "countryCode": "[MY_COUNTRY_CODE]",
    "principalSubdivision": "[MY_REGION]",
    "principalSubdivisionCode": "[MY_REGION_CODE]",
    "city": "[MY_CITY]",
    "locality": "[MY_LOCALITY]",
    "postcode": "",
    "plusCode": "[MY_PLUS_CODE]",
        "administrative": [
            {
                "name": "[MY_COUNTRY_NAME]",
                "description": "pa\u00eds del suroeste de Europa",
                "isoName": "[MY_COUNTRY_ISO_NAME]",
                "order": 2,
                "adminLevel": 2,
                "isoCode": "[MY_COUNTRY_ISO_CODE]",
                "wikidataId": "[MY_WIKIDATA_ID]",
                "geonameId": [MY_GEONAME_ID]
            },
            {...},
            {...}
        ],
        "informative": [
            {
                "name": "Europa",
                "description": "continente ba\u00f1ado principalmente por el Atl\u00e1ntico",
                "isoName": "Europe",
                "order": 1,
                "isoCode": "EU",
                "wikidataId": "Q46",
                "geonameId": 6255148
            },
            {...}
        ]
    },
    "timeZone": {
        "ianaTimeId": "[MY_TIMEZONE]",
        "displayName": "[MY_TIMEZONE_NAME]",
        "effectiveTimeZoneFull": "Central European Standard Time",
        "effectiveTimeZoneShort": "CET",
        "utcOffsetSeconds": 3600,
        "utcOffset": "+01",
        "isDaylightSavingTime": false,
        "localTime": "2025-02-01T10:30:04.4715676"
    }
}

Phone and Email Verification

Availables here: https://www.bigdatacloud.com/phone-email-verification

Network Engineering

Availables here: https://www.bigdatacloud.com/network-engineering

ipapi.com

Service BIO:

Web site: https://ipapi.com/
Documentation: https://ipapi.com/quickstart | https://ipapi.com/documentation
Susbscription type: Allow FREE, but subject to 100 "requests" per month.

APIKey EndPoints

Info about My IP

Requires only the APIKey.

Sample Request

# PowerShell
Clear-Host;
$MyIpapiAPIKey = "[MY_IPAPI_API_KEY]";
$RootURL = "http://api.ipapi.com";
$BaseURL = "${RootURL}/api";

$MyIpapiInfo = IRM "${BaseURL}/check?access_key=${MyIpapiAPIKey}"
$MyIpapiInfo;
$MyIpapiInfo | ConvertTo-Json -Depth 9;

Sample Response

{
    "ip": "[MY_IP]",
    "type": "ipv4",
    "continent_code": "EU",
    "continent_name": "Europe",
    "country_code": "[MY_COUNTRY_CODE]",
    "country_name": "[MY_COUNTRY_ISO_NAME]",
    "region_code": "[MY_REGION_CODE]",
    "region_name": "[MY_REGION]",
    "city": "[MY_CITY]",
    "zip": "[MY_POBOX]",
    "latitude": [MY_LATITUDE],
    "longitude": [MY_LONGITUDE],
    "msa": null,
    "dma": null,
    "radius": null,
    "ip_routing_type": "fixed",
    "connection_type": "dsl",
    "location": {
        "geoname_id": [MY_GEONAME_ID],
        "capital": "[MY_CITY]",
        "languages": [
            {
                "code": "[MY_COUNTRY_CODE]",
                "name": "[MY_COUNTRY_NAME]",
                "native": "[ONE_LANGUAGE]"
            },
            {
                "code": "[MY_COUNTRY_CODE]",
                "name": "[MY_COUNTRY_NAME]",
                "native": "[OTHER_LANGUAGE]"
            },
            {...more languages...}
        ],
        "country_flag": "[MY_COUNTRY_FLAG]",
        "country_flag_emoji": "[MY_COUNTRY_FLAG_EMOJI]",
        "country_flag_emoji_unicode": "[MY_COUNTRY_FLAG_EMOJI_UNICODE]",
        "calling_code": "[MY_COUNTRY_CALLING_CODE]",
        "is_eu": true
    }
}

Info about ANY IP

Requires an APIKey and an IP.
We can retrieve our IP from here
Just, in the previous endpoin, instead of: /check put any IP, for example our own IP: ${MyIpifyIP}.

Sample Request

# PowerShell
Clear-Host;
$MyIpapiAPIKey = "[MY_IPAPI_API_KEY]";
$RootURL = "http://api.ipapi.com";
$BaseURL = "${RootURL}/api";

## My IP
$MyIpifyIP = ( IRM "https://api64.ipify.org?format=json" ).ip;
$MyIpifyIP;

$MyIpapiInfo = IRM "${BaseURL}/${MyIpifyIP}?access_key=${MyIpapiAPIKey}"
$MyIpapiInfo;
$MyIpapiInfo | ConvertTo-Json -Depth 9;

Sample Response

{
    "ip": "[MY_IP]",
    "type": "ipv4",
    "continent_code": "EU",
    "continent_name": "Europe",
    "country_code": "[MY_COUNTRY_CODE]",
    "country_name": "[MY_COUNTRY_ISO_NAME]",
    "region_code": "[MY_REGION_CODE]",
    "region_name": "[MY_REGION]",
    "city": "[MY_CITY]",
    "zip": "[MY_POBOX]",
    "latitude": [MY_LATITUDE],
    "longitude": [MY_LONGITUDE],
    "msa": null,
    "dma": null,
    "radius": null,
    "ip_routing_type": "fixed",
    "connection_type": "dsl",
    "location": {
        "geoname_id": [MY_GEONAME_ID],
        "capital": "[MY_CITY]",
        "languages": [
            {...several languages...}
        ],
        "country_flag": "[MY_COUNTRY_FLAG]",
        "country_flag_emoji": "[MY_COUNTRY_FLAG_EMOJI]",
        "country_flag_emoji_unicode": "[MY_COUNTRY_FLAG_EMOJI_UNICODE]",
        "calling_code": "[MY_COUNTRY_CALLING_CODE]",
        "is_eu": true
    }
}

AbstractAPI.com

Service BIO:

Web site: https://www.abstractapi.com/
Documentation: https://app.abstractapi.com/dashboard
Susbscription type: Allow FREE, but subject to 1000 "credits" per month.

APIKey EndPoints

IP Geolocation

Requires an APIKey and an optional IP.
We can retrieve our IP from here

Sample Request

# PowerShell
Clear-Host;
$MyAAPIKey = "[MY_AAPI_API_KEY]";
$RootURL = "https://ipgeolocation.abstractapi.com";
$BaseURL = "${RootURL}/v1";

## Without IP
## ----------------
$MyAApiInfo = IRM "${BaseURL}/?api_key=${MyAAPIKey}"
$MyAApiInfo;
$MyAApiInfo | ConvertTo-Json -Depth 9;

## With any IP
## ----------------
## My IP
$MyIpifyIP = ( IRM "https://api64.ipify.org?format=json" ).ip;
$MyIpifyIP;

$MyAApiInfo = IRM "${BaseURL}/?api_key=${MyAAPIKey}&ip_address=${MyIpifyIP}"
$MyAApiInfo;
$MyAApiInfo | ConvertTo-Json -Depth 9;

Sample Response

{
    "ip_address": "[MY_IP]",
    "city": "[MY_CITY]",
    "city_geoname_id": [MY_CITY_GEONAME_ID],
    "region": "[MY_REGION]",
    "region_iso_code": "[MY_REGION_ISO_CODE]",
    "region_geoname_id": [MY_REGION_GEONAME_ID],
    "postal_code": "[MY_POBOX]",
    "country": "[MY_COUNTRY_ISO_NAME]",
    "country_code": "[MY_COUNTRY_CODE]",
    "country_geoname_id": [MY_COUNTRY_CODE_GEONAME_ID],
    "country_is_eu": true,
    "continent": "Europe",
    "continent_code": "EU",
    "continent_geoname_id": 6255148,
    "longitude": [MY_LONGITUDE_SHORT],
    "latitude": [MY_LATITUDE_SHORT],
    "security": {
        "is_vpn": false
    },
    "timezone": {
        "name": "[MY_TIMEZONE]",
        "abbreviation": "CET",
        "gmt_offset": 1,
        "current_time": "11:04:34",
        "is_dst": false
    },
    "flag": {
        "emoji": "[MY_COUNTRY_FLAG_EMOJI]",
        "unicode": "[MY_COUNTRY_FLAG_EMOJI_UNICODE]",
        "png": "[MY_COUNTRY_FLAG_PNG]",
        "svg": "[MY_COUNTRY_FLAG_SVG]"
    },
    "currency": {
        "currency_name": "Euros",
        "currency_code": "EUR"
    },
    "connection": {
        "autonomous_system_number": [MY_ASN],
        "autonomous_system_organization": "[MY_ASN_NAME]",
        "connection_type": null,
        "isp_name": null,
        "organization_name": null
    }
}

ipify.com

Service BIO:

Web site: https://www.ipify.org/
Documentation: https://geo.ipify.org/docs
Susbscription type: Allow FREE, but subject to 1000 "credits" per month.

FREE EndPoints

My IP

Sample Request

# PowerShell
Clear-Host;
$BaseURL = "https://api64.ipify.org?format=json";
$Response = IRM "${BaseURL}";
$Response;
$Response | ConvertTo-Json -Depth 9;

## My IP
$MyIpifyIP = $Response.ip;
$MyIpifyIP;

Sample Response

{
    "ip":  "[MY_IP]"
}

ipify.com only offers the "My IP" for free.
With the "subscription plan", more/extra information is available.

APIKey EndPoints

My Info

Sample Request

# PowerShell
Clear-Host;
$MyIpifyAPIKey = "[MY_IPIFY_API_KEY]";
$RootURL = "https://geo.ipify.org";
$BaseURL = "${RootURL}/api/v2";

$MyIpifyInfo = IRM "${BaseURL}/country?apiKey=${MyIpifyAPIKey}&ipAddress=${MyIpifyIP}"
$MyIpifyInfo;
$MyIpifyInfo | ConvertTo-Json -Depth 9;

Sample Response

{
    "ip": "[MY_IP]",
    "location": {
        "country": "[MY_COUNTRY_CODE]",
        "region": "[MY_REGION]",
        "timezone": "+00:00"
    },
    "as": {
        "asn": [MY_ASN],
        "name": "[MY_ASN_NAME]",
        "route": "[MY_ASN_NETWORK]",
        "domain": "[MY_ASN_WEBSITE]",
        "type": ""
    },
    "isp": "[MY_ASN_NAME]"
}

My Extended Info

Sample Request

# PowerShell
Clear-Host;
$MyIpifyAPIKey = "[MY_IPIFY_API_KEY]";
$RootURL = "https://geo.ipify.org";
$BaseURL = "${RootURL}/api/v2";

$MyIpifyExtendedInfo = IRM "${BaseURL}/country,city?apiKey=${MyIpifyAPIKey}&ipAddress=${MyIpifyIP}"
$MyIpifyExtendedInfo;
$MyIpifyExtendedInfo | ConvertTo-Json -Depth 9;

Sample Response

{
    "ip": "[MY_IP]",
    "location": {
        "country": "[MY_COUNTRY]",
        "region": "[MY_REGION]",
        "city": "[MY_CITY]",
        "lat": [MY_LATITUDE_SHORT],
        "lng": [MY_LONGITUDE_SHORT],
        "postalCode": "[MY_POBOX]",
        "timezone": "+00:00",
        "geonameId": [MY_GEONAME_ID]
    },
    "as": {
        "asn": [MY_ASN],
        "name": "[MY_ASN_NAME]",
        "route": "[MY_ASN_NETWORK]",
        "domain": "[MY_ASN_WEBSITE]",
        "type": ""
    },
    "isp": "[MY_ASN_NAME]"
}

My Balance

Sample Request

# PowerShell
Clear-Host;
$MyIpifyAPIKey = "[MY_IPIFY_API_KEY]";
$RootURL = "https://geo.ipify.org";
$BaseURL = "${RootURL}/api/v2";

$MyIpifyBalance = IRM "${RootURL}/service/account-balance?apiKey=${MyIpifyAPIKey}"
$MyIpifyBalance;
$MyIpifyBalance | ConvertTo-Json -Depth 9;

Sample Response

{
    "credits": [MY_REMAINING_CREDITS]
}

Bluesky OAuth2 Client, with Vanilla JavaScript

PIPO — Tue, 21 Jan 2025 23:23:43 +0000

Hi, there! ;^)

Introduction

This post talks about integrating Bluesky Authentication (OAuth + DPoP) in a "serverless" client application, ruled with only "Vanilla JavaScript".
Fine for You? Ok... Let's go!

DISCLAIMER

This post is merely to illustrate "how-to". It's not a "working example"; mainly 'cause the tokens expire! ;^)

If you see any error, please don't doubt on contacting me to correct it!

The app source code is in github

Our application

The "OAuth" word

Let's say we want to develop a serverless application, open to whoever who wants to access, BUT we need the users to authenticate themselves to gain access to it.

One option is to request the incoming user to auto-register within the application directly (create an account and generate a "credential"; usually), a combination of a login with a password for that account. But, another way to authenticate themself is to "trust" a third-party authority.

Just like Google does, in this case Bluesky also provides a way for bluesky users to authenticate where it's needed.

This is driven by the OAuth2 Protocol.

More info about how OAuth works within Bluesky can be found here: OAuth - AT Protocol.

The Client Metadata... What's that?

In order that our brand new web application (let's suppose it's a Javascript-based application) can use this authentication mechanism from Bluesky, the Bluesky Authentication Services/Servers MUST recognize our application. How can we do it?
Easy! Generating a "Client Metadata" file, which will hold all the information that the Bluesky Authentication Services/Servers need to provide the app the information about the user.

With this file, as stated above in the "OAuth Protocol" page, "Automated client registration using client metadata" approach is followed. This means that there will be no need to "register" our brand-new application in any Authentication Server; it is enough to create a "metadata" file to automatically be a "Bluesky OAuth Client".

So in order for this to work, the only thing we need in our system is a "client-metadata.json" file, and make it accesible under the https:// protocol.

NOTE: We can name the file with any name we want; even more, we can place it anywhere; it's just a descriptor.

So then, we must create a JSON file that the Bluesky authentication servers will query to identify our application; for them, our applications will be a "Client Application" described by that JSON file.

The "metadata file", for our "client application", MUST be accesible from anywhere in the internet.

NOTE: As an example, we've deployed a file in this url: https://madrilenyer.neocities.org/bsky/oauth/client-metadata.json. If you click in that link, you will see the contents of it; directly.

So, to show an example, and following the Bluesky guidelines here and here, we've set up a "metadata file" that looks like this:

client-metadata.json:

{
  "client_id":"https://madrilenyer.neocities.org/bsky/oauth/client-metadata.json",
  "application_type":"web",
  "grant_types":[
    "authorization_code",
    "refresh_token"
  ],
  "scope":"atproto transition:generic transition:chat.bsky",
  "response_types":[
    "code id_token",
    "code"
  ],
  "redirect_uris":[
    "https://madrilenyer.neocities.org/bsky/oauth/callback/"
  ],
  "dpop_bound_access_tokens":true,
  "token_endpoint_auth_method":"none",
  "client_name":"Madrilenyer Example Browser App",
  "client_uri":"https://madrilenyer.neocities.org/bsky/"
}

This JSON file "describes" an application that "wants to be identified as a Bluesky OAuth 'Client Application'".

Now, we're ready to request from the users an authentication against Bluesky.

Let's use... A programming language

The problem here is that there are several implementations of "how-to-do" this integration BUT with modern frameworks. The guys from @atproto.com have implemented a wonderful pack in TypeScript and some guys has some solutions with NodeJS.

But, personally, I prefer "Vanilla Javascript", first, just to understand the basics on the mechanism; just to learn it, before start using a "library" that hides almost all. The problem is that there is NOTHING out there...

So this is the reason why I'm writing this post.

The basics: The context

Ok; so here we are.
We are trying to tell an incoming user to identify himself to access our application.
And we offer him to "Sign-In with Bluesky", but... What do we really need?
What is the minimum data from the user that we need to perform a validation process with an authenticated user?

The user's Handle

First of all, we need a "handle".
The only thing we need from the user is his handle.

NOTE: A "Bluesky Handle" is all that text following your "Bluesky Profile URL"; the characters after: "https://bsky.app/profile/_______________________".

This is our "Bluesky *handle", our "Bluesky *account**"; for instance, mine is: madrilenyer.bsky.social.

NOTE: Jay (Bluesky CEO) wrote time ago a post about this. If you need, you can dive into the Bluesky Docs for more information about handles, PDS's, accounts, AT Protocol...

The user's DID

So, once we know the user's "handle", the first step is to retrieve the user's did: The user's "Decentralized ID".

NOTE: What the hell is a "DID" and how does it looks like? Well... Click here or here

To gather user's "did", we will should call an API (using Javascript, as I said): Retrieve DID
Just, open this link in a browser and wait.

If you look at the URL, you'll see something like: [https://bsky.social/xrpc/com.atproto.identity.resolveHandle?handle=**madrilenyer.bsky.social**].
This means that, calling this URL but changing the "handle", you will receive the "did" of the corresponding "handle".

NOTE: Wanna try yours? ;^)

So, this call will show us our did:

{
  "did": "did:plc:tjc27aje4uwxtw5ab6wwm4km"
}

NOTE: This did is for the Bluesky handle: [madrilenyer.bsky.social]

    // ------------------------------------------
    //   Javascript
    // ------------------------------------------
    const USER_HANDLE = "madrilenyer.bsky.social";
    const APP_CLIENT_ID = "https://madrilenyer.neocities.org/bsky/oauth/client-metadata.json";
    const APP_CALLBACK_URL = "https://madrilenyer.neocities.org/bsky/oauth/callback/";

    let userDid = null;

    let url = "https://bsky.social/xrpc/com.atproto.identity.resolveHandle?handle=" + USER_HANDLE;
    fetch( url ).then( response => {
        // Process the HTTP Response
        return response.json();
    }).then( data => {
        // Process the HTTP Response Body
        // Here, we gather the "did" item in the received json.
        userDid = data.did;
    });

The user's DID Document

Once with the did, and with the help of the PLC API, our next step is to retrieve the user/handle's DID Document.
We do this calling a specific API EndPoint (https://plc.directory/) followed with the user's did ("did:plc:tjc27aje4uwxtw5ab6wwm4km"); not the user's handle ("madrilenyer.bsky.social").

NOTE: General information about DID, PLC's and so on, can be achieved here. Detailed info about the DID PLC here
NOTE: This also can help: did:plc Directory Server API (0.1)

So, upon calling that URL, our DID Document (generated -or stored- by Bluesky) is something like this (JSON File Format):

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/multikey/v1",
    "https://w3id.org/security/suites/secp256k1-2019/v1"
  ],
  "id": "did:plc:tjc27aje4uwxtw5ab6wwm4km",
  "alsoKnownAs": [
    "at://madrilenyer.bsky.social"
  ],
  "verificationMethod": [
    {
      "id": "did:plc:tjc27aje4uwxtw5ab6wwm4km#atproto",
      "type": "Multikey",
      "controller": "did:plc:tjc27aje4uwxtw5ab6wwm4km",
      "publicKeyMultibase": "zQ3shQzL5vznqAdHiD6wvKRfH5xEaDXWpP3JTGQYAfhQo6Dz5"
    }
  ],
  "service": [
    {
      "id": "#atproto_pds",
      "type": "AtprotoPersonalDataServer",
      "serviceEndpoint": "https://velvetfoot.us-east.host.bsky.network"
    }
  ]
}

Coding it in Vanilla JavaScript:

    // ------------------------------------------
    //   Javascript
    // ------------------------------------------
    let userDidDocument = null;
    let userPDSURL = null;

    let url = "https://plc.directory/" + USER_HANDLE;
    fetch( url ).then( response => {
        // Process the HTTP Response
        return response.json();
    }).then( data => {
        // Process the HTTP Response Body
        userDidDocument = data;
        userPDSURL = userDidDocument.service[0].serviceEndpoint;
    });

The PDS URL

As you may notice in that response, within the "DID Document" there is a special key under: <did_document>.service.serviceEndpoint, which points to an URL: https://velvetfoot.us-east.host.bsky.network

This is the URL of our PDS Server.

NOTE: Again... What the hell is a "PDS Server"? Well... Click here. For those using Mastodon is just like an "instance".

If you open that URL in the browser (the URL of the PDS Server; again, publicly accesible), the only thing you see should be something like this:

This is an AT Protocol Personal Data Server (PDS): https://github.com/bluesky-social/atproto

Most API routes are under /xrpc/

So... This means that, whenever we need to request something to our PDS Server, we must build an URL starting with something like:

https://velvetfoot.us-east.host.bsky.network/xrpc/[whatever_follows]

The PDS Metadata

Another thing to retrieve is the PDS Server Metadata. This is basic information that the server exposes to anyone, and is accesible at this URL: https://velvetfoot.us-east.host.bsky.network/.well-known/oauth-protected-resource.

The response is something like this:

{
  "resource": "https://velvetfoot.us-east.host.bsky.network",
  "authorization_servers": [
    "https://bsky.social"
  ],
  "scopes_supported": [],
  "bearer_methods_supported": [
    "header"
  ],
  "resource_documentation": "https://atproto.com"
}

NOTE: Changing the "hostname" part of the URL (https://velvetfoot.us-east.host.bsky.network) by another PDS Server host direction, will produce similar results.

Just like before, in this JSON there is also a special entry under: <pds_metadata>.authorization_servers, normally with only one entry (in JSON format, it's an array) and, in this case, this entry represents the Authorization Server this PDS uses; in this case, our PDS is pointing to this Authorization Server: https://bsky.social.

This URL, the one of the Authorization Server, is needed because ANY protected request to our PDS Server, protected with OAuth2, will need an user token, that can only be obtained FROM the Authorization Server once we are authenticated against it.

This means that, first of all, we have to identify ourselves against that Authentication/Authorization Server in order to allow that third-party app to retrieve our "user token" to perform whatever action the user wants.

So, let's take a look to the "Authentication/Authorization Server Metadata", if any.

    // ------------------------------------------
    //   Javascript
    // ------------------------------------------
    let userPDSMetadata = null;
    let userAuthServerURL = null;

    let url = userPDSURL + "/.well-known/oauth-protected-resource";
    fetch( url ).then( response => {
        // Process the HTTP Response
        return response.json();
    }).then( data => {
        // Process the HTTP Response Body
        userPDSMetadata = data;
        userAuthServerURL = userPDSMetadata.authorization_servers[0];
    });

The Authorization Server Discovery

The next step is to gather the metadata of the Authorization Server. This is also part of the OAuth2 protocol (known as: "Discovery") and, in this case, can be accessed with: https://bsky.social/.well-known/oauth-authorization-server

Once again, is publicly accesible, so if we click on that URL, we will receive this information; the "Discovery" information for our Authorization Server:

{
  "issuer":"https://bsky.social",
  "scopes_supported":[
    "atproto",
    "transition:generic",
    "transition:chat.bsky"
  ],
  "subject_types_supported":[
    "public"
  ],
  "response_types_supported":[
    "code"
  ],
  "response_modes_supported":[
    "query",
    "fragment",
    "form_post"
  ],
  "grant_types_supported":[
    "authorization_code",
    "refresh_token"
  ],
  "code_challenge_methods_supported":[
    "S256"
  ],
  "ui_locales_supported":[
    "en-US"
  ],
  "display_values_supported":[
    "page",
    "popup",
    "touch"
  ],
  "authorization_response_iss_parameter_supported":true,
  "request_object_signing_alg_values_supported":[
    "RS256",
    "RS384",
    "RS512",
    "PS256",
    "PS384",
    "PS512",
    "ES256",
    "ES256K",
    "ES384",
    "ES512",
    "none"
  ],
  "request_object_encryption_alg_values_supported":[

  ],
  "request_object_encryption_enc_values_supported":[

  ],
  "request_parameter_supported":true,
  "request_uri_parameter_supported":true,
  "require_request_uri_registration":true,
  "jwks_uri":"https://bsky.social/oauth/jwks",
  "authorization_endpoint":"https://bsky.social/oauth/authorize",
  "token_endpoint":"https://bsky.social/oauth/token",
  "token_endpoint_auth_methods_supported":[
    "none",
    "private_key_jwt"
  ],
  "token_endpoint_auth_signing_alg_values_supported":[
    "RS256",
    "RS384",
    "RS512",
    "PS256",
    "PS384",
    "PS512",
    "ES256",
    "ES256K",
    "ES384",
    "ES512"
  ],
  "revocation_endpoint":"https://bsky.social/oauth/revoke",
  "introspection_endpoint":"https://bsky.social/oauth/introspect",
  "pushed_authorization_request_endpoint":"https://bsky.social/oauth/par",
  "require_pushed_authorization_requests":true,
  "dpop_signing_alg_values_supported":[
    "RS256",
    "RS384",
    "RS512",
    "PS256",
    "PS384",
    "PS512",
    "ES256",
    "ES256K",
    "ES384",
    "ES512"
  ],
  "client_id_metadata_document_supported":true
}

There are some entries here to use to retrieve our "user token"... Let's begin:

authorization_endpoint: We will need this URL to request authorization to access to the user's token. In this case, this entry is: https://bsky.social/oauth/authorize
token_endpoint: This is the URL to request the user's access token In this case, this entry is: https://bsky.social/oauth/token
pushed_authorization_request_endpoint (PAR EndPoint): A "preRequirement". All calls to the Authorization Server, trying to obtain an user's token, must be validated, as per RFC 9126 In this case, this entry is: https://bsky.social/oauth/par

And here ends the "public accessible" steps for authenticate users against our application.
From now on, we must continue with the development of the JavaScript application; 'cause other "types of requests" are needed, not as easy as "click here".

    // ------------------------------------------
    //   Javascript
    // ------------------------------------------
    let userAuthServerDiscovery = null;
    let userAuthorizationEndPoint = null;
    let userTokenEndPoint = null;
    let userPAREndPoint = null;

    let url = userAuthServerURL + "/.well-known/oauth-authorization-server";
    fetch( url ).then( response => {
        // Process the HTTP Response
        return response.json();
    }).then( data => {
        // Process the HTTP Response Body
        userAuthServerDiscovery   = data;
        userAuthorizationEndPoint = userAuthServerDiscovery.authorization_endpoint;
        userTokenEndPoint         = userAuthServerDiscovery.token_endpoint;
        userPAREndPoint           = userAuthServerDiscovery.pushed_authorization_request_endpoint;
    });

Authentication

As a help, Bluesky has an entry explaining "how-to" perform all these steps... except the last one. We'll see later.

PAR Request

Once in this point, we must request the PAR Authorization; this can be done using PKCE.

Recap: In order to retrieve the user's token, we must:

Call the "token_endpoint".
But, prior to it, we need to get an authorization, calling the "authorization_endpoint".
And also, before above steps, we need to tell the server we are going to perform those operations, by using the "pushed_authorization_request_endpoint", the PAR EndPoint.

NOTE: The OAuth 2.0 Pushed Authorization Requests specification is here

Back to our Javascript area, we will need to generate three things:

state: First, we need a "state"; a string with 28 random characters. For our purposes, this value should be: 2e94cf77e8b0ba2209dc6dcb90018c8d044ac31cb526fc4823278585
code_verifier: Later, a "code_verifier" is needed; just like before. For our purposes, this value should be: 46148ae0fd74b698a5f78efc44a8f76f1fd778602b14b46a2318a814
code_challenge: Finally, from the "code_verifier" we need to generate a "code_challenge". Basically, this: base64urlencode( sha256( code_verifier ) ); For our purposes, this value should be: URQ-2arwHpJzNwcFPng-_IE3gRGGBN0SVoFMN7wEiWI

NOTE: We'll need more parameters, but all of them are well known, at this point:
+ Some static constants (code_challenge_method, scope)
+ Some data from our client-metadata.json file (client_id, redirect_uri, login_hint)
+ and some of the just generated data (code_challenge, state)

Now, with all that information, we prepare a POST request against the URL indicated in the pushed_authorization_request_endpoint key (in this case: https://bsky.social/oauth/par), with these content-type: application/x-www-form-urlencoded, and this "body":

response_type=code&code_challenge_method=S256&scope=atproto+transition%3Ageneric&client_id=https%3A%2F%2Fmadrilenyer.neocities.org%2Fbsky%2Foauth%2Fclient-metadata.json&redirect_uri=https%3A%2F%2Fmadrilenyer.neocities.org%2Fbsky%2Foauth%2Fcallback%2F&code_challenge=URQ-2arwHpJzNwcFPng-_IE3gRGGBN0SVoFMN7wEiWI&state=2e94cf77e8b0ba2209dc6dcb90018c8d044ac31cb526fc4823278585&login_hint=madrilenyer.bsky.social

Splitted:

  response_type=code
    &code_challenge_method=S256
    &scope=atproto+transition%3Ageneric
    &client_id=https%3A%2F%2Fmadrilenyer.neocities.org%2Fbsky%2Foauth%2Fclient-metadata.json
    &redirect_uri=https%3A%2F%2Fmadrilenyer.neocities.org%2Fbsky%2Foauth%2Fcallback%2F
    &code_challenge=URQ-2arwHpJzNwcFPng-_IE3gRGGBN0SVoFMN7wEiWI
    &state=2e94cf77e8b0ba2209dc6dcb90018c8d044ac31cb526fc4823278585
    &login_hint=madrilenyer.bsky.social

Note that we send the state and the code_challenge; not the code_challenge; we will use this last value to check things later.

This is a sample of the response (201 (Created)):

{
  "request_uri": "urn:ietf:params:oauth:request_uri:req-df74117722b7f1e7d807d4244a8dae0a",
  "expires_in": 299
}

We need the request_uri item for the next step.
And also, in the headers of the response, we can find out the: [DPoP-Nonce] header; known as "the nonce". We will need its value later.

    // ------------------------------------------
    //   Javascript
    // ------------------------------------------
    let dpopNonce = null;
    let userAuthServerRequestURI = null;

    // The AuthServer Discovery Information
    // ------------------------------------------
    let url = userAuthServerURL + "/.well-known/oauth-authorization-server";
    fetch( url ).then( response => {
        // Process the HTTP Response
        return response.json();
    }).then( data => {
        // Process the HTTP Response Body
        userAuthServerDiscovery   = data;
        userAuthorizationEndPoint = userAuthServerDiscovery.authorization_endpoint;
        userTokenEndPoint         = userAuthServerDiscovery.token_endpoint;
        userPAREndPoint           = userAuthServerDiscovery.pushed_authorization_request_endpoint;
    });

    // The state
    // ------------------------------------------
    let stateArray = new Uint32Array(28);
    window.crypto.getRandomValues(stateArray);
    let state = Array.from(stateArray, dec => ('0' + dec.toString(16)).substr(-2)).join('');

    // The code verifier
    // ------------------------------------------
    let codeVerifierArray = new Uint32Array(28);
    window.crypto.getRandomValues(codeVerifierArray);
    let codeVerifier = Array.from(codeVerifierArray, dec => ('0' + dec.toString(16)).substr(-2)).join('');

    // The code verifier challenge
    // ------------------------------------------
    let hashedCodeVerifier = await sha256(codeVerifier);
    let codeChallenge = base64urlencode(hashedCodeVerifier);

    // Build up the URL.
    // Just, to make it simple! I know there are better ways to do this, BUT...
    // ------------------------------------------
    let url = userPAREndPoint;
    let body = "response_type=code";
    body += "&code_challenge_method=S256";
    body += "&scope=" + encodeURIComponent( "atproto transition:generic" ); // MUST match the scopes in the client-metadata.json
    body += "&client_id=" + encodeURIComponent( APP_CLIENT_ID );
    body += "&redirect_uri=" + encodeURIComponent( APP_CALLBACK_URL );
    body += "&code_challenge=" + codeChallenge;
    body += "&state=" + state;
    body += "login_hint=" + USER_HANDLE;

    // TuneUp and perform the call
    // ------------------------------------------
    let fetchOptions = {
        method: 'POST',
        headers: {
            'Content-Type': "application/x-www-form-urlencoded"
        },
        body: body
    }
    fetch( url, fetchOptions ).then( response => {
        // Process the HTTP Response
        dpopNonce = response.headers.get( "dpop-nonce" );
        return response.json();
    }).then( data => {
        // Process the HTTP Response Body
        userAuthServerRequestURI = data.request_uri;
    });

User's Authentication

We've got enough to request the user to authenticate against the Bluesky Server... How?

Well, we need to "build-up" a new URL to redirect the user to.
It's something like:

[`authorization_endpoint`]?client_id=[client_id]&request_uri=[`request_uri`]

NOTE: The URL parameters need to e encoded; you can use this encoder, thought Javacript uses encodeURIComponent

In our case, our URL looks like this (values may not be the same):

https://bsky.social/oauth/authorize?client_id=https%3A%2F%2Fmadrilenyer.neocities.org%2Fbsky%2Foauth%2Fclient-metadata.json&request_uri%3Durn%3Aietf%3Aparams%3Aoauth%3Arequest_uri%3Areq-df74117722b7f1e7d807d4244a8dae0a

Coded in our Vanilla Javascript:

    // ------------------------------------------
    //   Javascript
    // ------------------------------------------

    // Buld up the URL.
    // ------------------------------------------
    let url = userAuthorizationEndPoint;
    url += "?client_id=" + encodeURIComponent( APP_CLIENT_ID );
    url += "&request_uri=" + encodeURIComponent( userAuthServerRequestURI );

    // Redirect the user to the Bluesky Auth Page
    // ------------------------------------------
    window.location = url;

The Bluesky OAuth Authentication Page

This URL (well... "similar"; as the validity is about some minutes, you may see an error page, if you click) leads the user to the Bluesky Authentication page.

In this page, the server requests from the user to authenticate and, if so, authorize the application to use your "acess_token" to perform "things" in your name.

Just like Google does, doesn't it? ;^)

Redirected Page

If, in that page (remember, 'Bluesky Authorization Page'), the user agrees and accepts to give permission to the application to use the "user's token", then the server will redirect the user's browser to the "Redirection/Callback Page".

Remember that "redirect_uri" parameter while the "PAR Request, above"? Yes, that parameter; one of the ones described in the "client-metadata.json" file, under the array (yes, you can state several URLs for the callback) identified with the key: redirect_uris.

Now, the flow comes back to our control. When the user lands in the "callback page", we will receive something like this:

https://madrilenyer.neocities.org/bsky/oauth/callback/?iss=https%3A%2F%2Fbsky.social&state=4e47aaac8cbd35ed1a2afff53ce6f4511898d7c2ef0e47b37d77110f&code=cod-b17f75f356b83f35e99c4d7664ed30442a9c79c5c37ecf88261d77db799d0c0f

Splitted:

https://madrilenyer.neocities.org/bsky/oauth/callback/
    ?iss=https%3A%2F%2Fbsky.social
    &state=4e47aaac8cbd35ed1a2afff53ce6f4511898d7c2ef0e47b37d77110f
    &code=cod-b17f75f356b83f35e99c4d7664ed30442a9c79c5c37ecf88261d77db799d0c0f

Three parameters:

iss: The "Authority"; in this case, the URL of the Bluesky Authorization Server
state: The "state" parameter we send before in the PAR Request, and
code: A (one single use) code that the application needs to retrieves the user's access token from the server.

    // ------------------------------------------
    //   Javascript
    // ------------------------------------------
    let receivedIss = null;
    let receivedState = null;
    let receivedCode = null;

    // Let's retrieve the values from the URL.
    // ------------------------------------------
    // Retrieve the URL.
    let thisURL = new URL(window.location);

    // Retrieve the "search" part from the url
    let parsedSearch = new URLSearchParams(thisURL.search);

    // Retrieve the data.
    let receivedIss = parsedSearch.get("iss");
    let receivedState = parsedSearch.get("state");
    let receivedCode = parsedSearch.get("code");

    // We should include here some checks (the 'iss', the 'state'...), BUT...

Access tokens and security

But there is still a problem; in order to retrieve the user's access token, the server requires from us to validate that we are the one who will handle the token. How do the application do this?

There is a "new" specification, under the OAuth protocol, named: "Demonstrate proof of possession (DPoP)".

NOTE: The DPoP specification is here
You can find an explanation about DPoP is here
Bluesky docs has also some information about this... here.

The DPoP

The idea of the DPoP data is to "bind" the client application to the user's access token; let's say, "this token will be used by this application", and no other one else. It's just another additional level of security, to avoid someone takes the token and uses it in another application.

The problem is that, to link both data (the token and the 'client application'), we need to use a cryptographic key. Javascript can generate such a key, and we can use it. The key component in this step is... Remember the "nonce"? Here it comes!

NOTE: A DPoP-Proof will be needed every time we need to call an endPoint protected with OAuth. Every DPoP-Proof will include the invoking URL, so we will have to (re-)generate new DPoP-Proofs for each request.

The User `access_token`

The first thing we need is the some-steps-ago-received dpop_nonce data. It came in a header during the call to the PAR EndPoint, and jher we will use it.

Another thing we need is to tell the Server "who are we", to "link" the user access_token to our future requests. For this, we need to create a DPoP-Prook; just in order to "pass" our cryptographic keys to the server.

For this first trial, we do NOT have yet the token, but we can setup a DPoP-Proof, something that identies us, how?
Well, let's use these three things:

userTokenEndPoint(**): The server's token endpoint
client_id: Let's say, the "APP_CLIENT_ID", and
dpopNonce: To create the DPoP-Proof with a crypto key

We will build up, again, an URL

    // ------------------------------------------
    //   Javascript
    //
    //   (maybe some steps are wrong 'typed')...
    // ------------------------------------------
    let userAccessToken = null;

    // Build up the URL.
    // ------------------------------------------
    let url = userTokenEndPoint;

    // The body of the call
    // ------------------------------------------
    let body = new URLSearchParams({
        // Fixed values
        'grant_type': 'authorization_code',
        // Constant values
        'client_id': encodeURIComponent( APP_CLIENT_ID ),
        'redirect_uri': encodeURIComponent( APP_CALLBACK_URL ),
        // Variable values
        'code': receivedCode,
        'code_verifier': codeVerifier
    });

    // Create the crypto key.
    // Must save it, 'cause we'll reuse it later.
    // ------------------------------------------
    let keyOptions = {
        name: "ECDSA",
        namedCurve: "P-256"
    };
    let keyPurposes = ["sign", "verify"];
    let key = await crypto.subtle.generateKey(keyOptions, false, keyPurposes).then(function(eckey) {
        return eckey;
    });
    let jwk = await crypto.subtle.exportKey("jwk", key.publicKey).then(function(keydata) {
        return keydata;
    });
    delete jwk.ext;
    delete jwk.key_ops;

    // Create the DPoP-Proof 'body' for this request.
    // ------------------------------------------
    let uuid = self.crypto.randomUUID();
    let dpop_proof_header = {
        typ: "dpop+jwt",
        alg: "ES256",
        jwk: jwk
    };
    let dpop_proof_payload = {
        iss: APP_CLIENT_ID, // Added
        jti: uuid,
        htm: "POST",
        htu: url,
        iat: Math.floor(Date.now() / 1000),
        nonce: dpopNonce
    };

    // Crypt and sign the DPoP-Proof header+body
    // ------------------------------------------
    const h = JSON.stringify(dpop_proof_header);
    const p = JSON.stringify(dpop_proof_payload);
    const partialToken = [
        Base64.ToBase64Url(Base64.utf8ToUint8Array(h)),
        Base64.ToBase64Url(Base64.utf8ToUint8Array(p)),
    ].join(".");
    const messageAsUint8Array = Base64.utf8ToUint8Array(partialToken);

    let signOptions = {
        name: "ECDSA",
        hash: { name: "SHA-256" },
    };
    let signatureAsBase64 = await crypto.subtle.sign(signOptions, key.privateKey, dpop_proof_payload)
    .then(function(signature) {
        return Base64.ToBase64Url(new Uint8Array(signature));
    });

    // The DPoP-Proof
    // ------------------------------------------
    let dpopProof = `${partialToken}.${signatureAsBase64}`;

    // TuneUp the call
    // ------------------------------------------
    let headers = {
        'DPOP': dpopProof,
        'Content-Type': 'application/x-www-form-urlencoded',
        'DPoP-Nonce': dpopNonce
    }
    let fetchOptions = {
        method: 'POST',
        headers: headers,
        body: body.toString()
    }

    // Finally, perform the call
    // ------------------------------------------
    let url = userTokenEndPoint;
    fetch( url, fetchOptions ).then( response => {
        // Process the HTTP Response
        return response.json();
    }).then( data => {
        // Process the HTTP Response Body
        authServerResponse = data;
        userAccessToken = data.access_token;
    });

In this point, the "authServerResponse" variable (the response from the authorization server) should look like:

    {
      "access_token": "eyJ0eXAiOiJhdCtqd3QiLCJhbGciOiJFUzI1NksifQ.eyJhdWQiOiJkaWQ6d2ViOnZlbHZldGZvb3QudXMtZWFzdC5ob3N0LmJza3kubmV0d29yayIsImlhdCI6MTczNzQ5ODM4NCwiZXhwIjoxNzM3NTAxOTg0LCJzdWIiOiJkaWQ6cGxjOnRqYzI3YWplNHV3eHR3NWFiNnd3bTRrbSIsImp0aSI6InRvay1jYzM0YTYzZjgwNWJjMWQ1MTdhNDNmNzU5YWU3ZjJiNCIsImNuZiI6eyJqa3QiOiJVVW1YVXAwMUxySkctak1WQnJHSG1DZy1FR3UyemRncFBMWjhGZDhYMFlNIn0sImNsaWVudF9pZCI6Imh0dHBzOi8vbWFkcmlsZW55ZXIubmVvY2l0aWVzLm9yZy9ic2t5L29hdXRoL2NsaWVudC1tZXRhZGF0YS5qc29uIiwic2NvcGUiOiJhdHByb3RvIHRyYW5zaXRpb246Z2VuZXJpYyIsImlzcyI6Imh0dHBzOi8vYnNreS5zb2NpYWwifQ.OoKiX0LIofSvCqCsZHKtSa7TrOAdWOlTPapu2EGrSxWeF8qkklaM8HXgtmEPTs1BEGIkol91zz32lE1jI72i9Q",
      "token_type": "DPoP",
      "refresh_token": "ref-5c3ecf03caded355cde56b394dae9d9922fda73434dc02642fcb3e1a5fe2e149",
      "scope": "atproto transition:generic",
      "expires_in": 3599,
      "sub": "did:plc:tjc27aje4uwxtw5ab6wwm4km"
    }
     */

NOTE: To "view" how is the "access_token", you can go to JWT

Here we go!

We've got the user's access token to make calls to the protected Bluesky EndPoints "on behalf" of the user.

Subsequent calls

From this point on, all DPoP-Proofs that need to be created (for subsequent calls) MUST include not only the "dpop-nonce" parameter, but also the "atHash", the access_token hashed.

    // ------------------------------------------
    //   Javascript
    // ------------------------------------------

    // For subsequent calls, we must include the
    // hash of the access token in the DPoP-Proof payload.
    // ------------------------------------------

    // Let's calculate the hash
    let encodedAccessToken = new TextEncoder().encode(userAccessToken);
    let atHash = await crypto.subtle.digest('SHA-256', encodedAccessToken)
    .then(function(hash) {        
        let base = Base64.ToBase64Url(new Uint8Array(hash));
        if (noPadding){
            base = base.replace(/\=+$/, '');
        }    
        return base;
    });

    // Regenerate the UUID.
    let uuid = self.crypto.randomUUID();

    // Add the hash in the DPoP-Proof payload.
    // The "url" is a new one.
    let dpop_proof_payload = {

        // This parameter LINKs the user access token
        // to the call & the application, thru the crypto key
        // ------------------------------------------
        ath: atHash,

        // The method can be "GET" or whatever.
        // ------------------------------------------
        htm: "POST",

        // The "url" should be distinct.
        // ------------------------------------------
        htu: url,

        // The "time stamp" is "now" (UNIX like)
        // ------------------------------------------
        iat: Math.floor(Date.now() / 1000),

        // The brand new uuid.
        // ------------------------------------------
        jti: uuid,

        // The rest of the parameters should be the same
        // ------------------------------------------
        iss: APP_CLIENT_ID,
        nonce: dpopNonce

    };

With this new DPoP-Proof, we can create a new "headers" object to perform the call.

    // ------------------------------------------
    //   Javascript
    // ------------------------------------------

    let headers: {
        'Content-Type': [whichever],
        'Accept': 'application/json',

        // The "Authorization" header now is
        // not a "Bearer" but a "DPoP". 
        // ------------------------------------------
        'Authorization': `DPoP ${userAccessToken}`,

        // The "DPoP-Proof" must be included also
        // in a proper header.
        // ------------------------------------------
        'DPoP': dpopProof
    },
    let fetchOptions = {
        method: 'POST',     // Or "GET", or...
        headers: headers,
        body: body          // Whatever. If needed
    }
    fetch( url, fetchOptions ).then( response => {
        // Process the HTTP Response

        // Normally, the "nonce" should come; to be checked.
        // ------------------------------------------
        dpopNonce = response.headers.get( "dpop-nonce" );
        return response.json();
    }).then( data => {
        // Process the HTTP Response Body
        // Whatever we expect.
    });

Final words

Of course, this is only a "pseudo-Javascript" code. If you want to use it, mind that the .then(...) functions are "Promises", so you have to program accordingly.

I've not included any check or "error control" in the code; it's just to explain the "happy path", the easiest way. If you plan to use this code as a base, remember to include all needed checks and error controls in the flow, as should be normal.

And, finally, "of course" is much, much better to use the official Bluesky TypeScript client. You can find here the source code.