internetdata (internetdata v1.17.1)

View Source

The official Erlang client for the InternetData API.

Build a client once with new/1, pass the term around, and release it with close/1. Every call answers {ok, Term} or {error, Error}; nothing here raises for a failure the API can report.

Absent is not false. A lookup answer is a map whose plan-gated keys are simply MISSING when your plan does not include them, which is a different answer from the key being present and false. Use maps:get(is_hosting, Result, undefined) or maps:find(is_hosting, Result) when the distinction matters, and maps:get(is_hosting, Result, false) when it does not.

Results are maps keyed by ATOMS for the fields the API documents, and by BINARIES for anything the server names: the format keys under schema, sample and size, the dataset column names inside a sample row, and an AS answer's whois. See internetdata_result for why.

Summary

Types

build names one build of a database, as a database.updated webhook gives it; absent or empty, a download fetches the build that is live.

The same set at runtime, because format() checks nothing once compiled.

Functions

Release the client's cache. Safe to call on a client that has none.

Every digest published for one dataset file.

Download one dataset file to Path, and answer how many bytes landed.

database_download/4 for the build build in Options names, as database_download_url/4 takes it. A transfer takes no timeout_ms.

Download one dataset file and hand back its bytes.

database_download_bytes/3 for the build build in Options names, as database_download_url/4 takes it. A transfer takes no timeout_ms.

The time-limited URL for one dataset file.

database_download_url/3 for the build build in Options names, as a database.updated webhook gives it (<<"20261105.0t53s5">>), so the file is the one whose sha256 the webhook carries. Absent or empty, the build that is live. A build is kept 7 days; past that the call answers bad_request with the message <<"BUILD_GONE">>. timeout_ms bounds each attempt of this call alone.

Your organization's recent download attempts, newest first.

Every format a database file is published in: the values format() takes, for checking one that came from a flag or a config file.

Every dataset FAMILY your organization may see, and where each one stands.

What is inside one dataset: column schema and sample rows per format, the row count, the byte size of each artifact, and the day it was built.

Whether an address is private, loopback, link-local, documentation, multicast or otherwise not routable, including the IPv6 equivalents and the 6to4 and Teredo ranges.

is_bogon/1, reachable from a client you already hold.

Every license_type the pinned spec publishes when it is not null.

What every database says about one address.

What InternetData knows about one autonomous system: its registration on every plan, and on a paid one its ASN Whois record and the prefixes it announces.

Look many addresses up in as few requests as possible.

What InternetData knows about one domain: whether it is registered and which record types it has on every plan, and on a paid one the records, its organization's IP ranges and whether it is disposable.

What this client's key is entitled to, and how much of it has been used.

What every database says about the address this client is calling from.

Build a client against production with no key.

Build a client.

The URL to open in the person's browser for the authorization code flow, from the challenge of oauth_create_pkce/0. Makes no request.

A fresh PKCE pair for one sign-in: 32 bytes from crypto's secure random source as a 43-character base64url verifier, its S256challenge, and the method. The challenge goes into the authorization URL, the verifier only to the exchange.

Start a device sign-in: show the person user_code and verification_uri, then call oauth_poll_device_token/3.

Exchange the code a sign-in's redirect brought back for tokens, once. CodeVerifier is the verifier whose challenge went into the authorization URL, and RedirectUri that URL's, exactly.

Exchange a device code for tokens, once. Until the person approves, this answers {error, #{error_code := <<"authorization_pending">>}}; oauth_poll_device_token/3 is the loop that waits for them.

Exchange a refresh token for a new pair. The token presented is spent, so keep the refresh_token this answers. Never retried; the answer may name the key in apikey_id but never carries apikey.

The authorization server's discovery document.

The S256 challenge for a PKCE verifier: its SHA-256, as unpadded base64url.

Wait for the person to approve a device sign-in, and answer its tokens.

Register a client for the authorization code flow, for an app that cannot serve a Client ID Metadata Document, and get its client_id for oauth_authorization_url/5 and oauth_exchange_authorization_code/6.

Revoke an access or a refresh token. A refresh token ends the whole grant and every token it issued, which is how a machine signs out.

Every standing the pinned spec publishes for a family in database_list/1. A value added later still reads through as a binary.

Types

address/0

-type address() :: binary() | string() | inet:ip_address().

authorization_url_options/0

-type authorization_url_options() ::
          #{scope => binary() | string(), state => binary() | string(), resource => binary() | string()}.

batch_options/0

-type batch_options() ::
          #{retries => non_neg_integer(),
            concurrency => pos_integer(),
            timeout_ms => pos_integer() | infinity}.

client/0

-opaque client()

device_authorization_options/0

-type device_authorization_options() ::
          #{scope => binary() | string(),
            resource => binary() | string(),
            timeout_ms => pos_integer() | infinity}.

download_options/0

-type download_options() :: #{build => binary() | string()}.

download_url_options/0

-type download_url_options() :: #{build => binary() | string(), timeout_ms => pos_integer() | infinity}.

downloads_options/0

-type downloads_options() :: #{limit => pos_integer(), timeout_ms => pos_integer() | infinity}.

build names one build of a database, as a database.updated webhook gives it; absent or empty, a download fetches the build that is live.

format/0

-type format() :: csvgz | mmdb.

The same set at runtime, because format() checks nothing once compiled.

lookup_options/0

-type lookup_options() :: #{retries => non_neg_integer(), timeout_ms => pos_integer() | infinity}.

oauth_options/0

-type oauth_options() :: #{timeout_ms => pos_integer() | infinity}.

options/0

-type options() ::
          #{api_key => binary() | string() | false | nil,
            base_url => binary() | string(),
            cache => #{max => pos_integer(), ttl_ms => pos_integer()} | false,
            concurrency => pos_integer(),
            retries => non_neg_integer(),
            timeout_ms => pos_integer() | infinity,
            http => internetdata_http:http_fun()}.

register_options/0

-type register_options() ::
          #{client_name => binary() | string(), timeout_ms => pos_integer() | infinity}.

Functions

close(_)

-spec close(client()) -> ok.

Release the client's cache. Safe to call on a client that has none.

database_checksums(Client, Id, Format)

-spec database_checksums(client(), binary() | string(), format()) ->
                            {ok, map()} | {error, internetdata_error:error()}.

Every digest published for one dataset file.

The whole set, not one algorithm: which digests a dataset publishes is the API's choice rather than ours, and they arrive nested under checksums.

database_download(Client, Id, Format, Path)

-spec database_download(client(), binary() | string(), format(), binary() | string()) ->
                           {ok, non_neg_integer()} | {error, internetdata_error:error()}.

Download one dataset file to Path, and answer how many bytes landed.

The transfer is streamed, so nothing beyond a single chunk is ever held in memory whatever the dataset weighs. The bytes go to a neighboring .part file that is renamed only once the whole body has arrived: a transfer that dies halfway leaves neither a truncated file that reads as a complete dataset nor a .part for the next attempt to append to.

The client's timeout_ms bounds the wait between chunks here rather than the whole transfer, because a deadline that suits a listing is the wrong one for a gigabyte while a stalled transfer is stalled at any size.

database_download(Client, Id, Format, Path, Options)

-spec database_download(client(),
                        binary() | string(),
                        format(),
                        binary() | string(),
                        download_options()) ->
                           {ok, non_neg_integer()} | {error, internetdata_error:error()}.

database_download/4 for the build build in Options names, as database_download_url/4 takes it. A transfer takes no timeout_ms.

database_download_bytes(Client, Id, Format)

-spec database_download_bytes(client(), binary() | string(), format()) ->
                                 {ok, binary()} | {error, internetdata_error:error()}.

Download one dataset file and hand back its bytes.

This holds the ENTIRE file in memory, and the published catalog runs from a few hundred bytes to several gigabytes, so reach for it at the small end and use database_download/4 for anything you have not checked database_metadata/2 for first. It transfers over exactly the same streamed path, so the bytes are the ones database_download/4 would have written.

database_download_bytes(Client, Id, Format, Options)

-spec database_download_bytes(client(), binary() | string(), format(), download_options()) ->
                                 {ok, binary()} | {error, internetdata_error:error()}.

database_download_bytes/3 for the build build in Options names, as database_download_url/4 takes it. A transfer takes no timeout_ms.

database_download_url(Client, Id, Format)

-spec database_download_url(client(), binary() | string(), format()) ->
                               {ok, binary()} | {error, internetdata_error:error()}.

The time-limited URL for one dataset file.

The API answers a 302 straight to object storage and this reads the Location without following it, so what comes back is a link that carries NO credential of yours and can be handed to whatever does the transfer. The link only has to be valid when a transfer starts, so one already running isn't cut off when it lapses.

database_download_url(Client, Id, Format, Options)

-spec database_download_url(client(), binary() | string(), format(), download_url_options()) ->
                               {ok, binary()} | {error, internetdata_error:error()}.

database_download_url/3 for the build build in Options names, as a database.updated webhook gives it (<<"20261105.0t53s5">>), so the file is the one whose sha256 the webhook carries. Absent or empty, the build that is live. A build is kept 7 days; past that the call answers bad_request with the message <<"BUILD_GONE">>. timeout_ms bounds each attempt of this call alone.

database_downloads(Client)

-spec database_downloads(client()) -> {ok, [map()]} | {error, internetdata_error:error()}.

database_downloads(Client, Options)

-spec database_downloads(client(), downloads_options()) ->
                            {ok, [map()]} | {error, internetdata_error:error()}.

Your organization's recent download attempts, newest first.

Refusals are listed too: a denial is what answers "it stopped working", and its absence answers nothing. limit defaults to 50 and the API clamps it to 200. timeout_ms bounds each attempt of this call alone, so a retried call can take longer in total.

database_formats()

-spec database_formats() -> [format()].

Every format a database file is published in: the values format() takes, for checking one that came from a flag or a config file.

database_list(Client)

-spec database_list(client()) -> {ok, [map()]} | {error, internetdata_error:error()}.

Every dataset FAMILY your organization may see, and where each one stands.

The whole published catalog, not only what you license: standing says whether a family is yours today (&lt;&lt;"licensed"&gt;&gt;), was (&lt;&lt;"expired"&gt;&gt;), or has never been bought (&lt;&lt;"unlicensed"&gt;&gt;). An open family is free under CC BY-SA 4.0, and every organization holds a standard license to it from the start, which standing and license_type report like any other.

A license covers a family (base), while a download names one of its versions, so the IDs the other calls take come from a family's versions rather than from the family itself.

database_metadata(Client, Id)

-spec database_metadata(client(), binary() | string()) ->
                           {ok, map()} | {error, internetdata_error:error()}.

What is inside one dataset: column schema and sample rows per format, the row count, the byte size of each artifact, and the day it was built.

Answered from the top level of the response rather than from an envelope, and cheap enough to poll: updated and entries say whether today's build is worth fetching without moving any of it. size is what to check a transfer against before starting one - the catalog spans five orders of magnitude.

is_bogon(Ip)

-spec is_bogon(binary() | string()) -> boolean().

Whether an address is private, loopback, link-local, documentation, multicast or otherwise not routable, including the IPv6 equivalents and the 6to4 and Teredo ranges.

These are the addresses lookup/2 answers locally, so they cost no request and no quota. Usable without a client.

is_bogon(Client, Ip)

-spec is_bogon(client(), binary() | string()) -> boolean().

is_bogon/1, reachable from a client you already hold.

license_types()

-spec license_types() -> [binary()].

Every license_type the pinned spec publishes when it is not null.

lookup(Client, Ip)

-spec lookup(client(), address()) ->
                {ok, internetdata_result:result()} | {error, internetdata_error:error()}.

lookup(Client, Ip, Options)

-spec lookup(client(), address(), lookup_options()) ->
                {ok, internetdata_result:result()} | {error, internetdata_error:error()}.

What every database says about one address.

Ip is text, or a tuple as inet:peername/1 and Cowboy's peer give it. A bogon is answered locally and never reaches the network. Everything else is served, then cached for this client alone. Text that is no IP address is a bad_request with nothing sent, and its message names lookup_asn/2 and lookup_domain/2, which look an AS and a domain up.

Options overrides the client's retries and timeout_ms for this call alone. timeout_ms bounds each attempt, so a retried call can take longer in total.

lookup_asn(Client, Asn)

-spec lookup_asn(client(), 0..4294967295) ->
                    {ok, internetdata_result:asn_result()} | {error, internetdata_error:error()}.

lookup_asn(Client, Asn, Options)

-spec lookup_asn(client(), 0..4294967295, lookup_options()) ->
                    {ok, internetdata_result:asn_result()} | {error, internetdata_error:error()}.

What InternetData knows about one autonomous system: its registration on every plan, and on a paid one its ASN Whois record and the prefixes it announces.

Asn is the AS number, sent as given; one the API cannot read is a bad_request. Never cached. Options is lookup/3's.

lookup_batch(Client, Ips)

-spec lookup_batch(client(), [address()]) ->
                      #{binary() =>
                            {ok, internetdata_result:result()} | {error, internetdata_error:error()}}.

lookup_batch(Client, Ips, Options)

-spec lookup_batch(client(), [address()], batch_options()) ->
                      #{binary() =>
                            {ok, internetdata_result:result()} | {error, internetdata_error:error()}}.

Look many addresses up in as few requests as possible.

Bogons are answered locally and cached answers are reused; everything else goes to the batch endpoint in chunks of up to 1000 addresses, with at most concurrency chunks in flight. Keyed by address rather than positional, so duplicates in the input collapse to a single entry and the caller never has to line two lists up. An address that fails carries its {error, Error} as its value, so one bad entry cannot lose the rest of the answers: the API reports a per-entry failure with the status the single lookup would have answered, and a chunk that fails as a whole marks every address in it. The batch endpoint needs a paid plan: without a key every address in a request of two or more carries an unauthorized error, and a free-plan key's request of two or more a bad_request (HTTP 402). A request of one address is answered as its lookup would be. Erlang maps have no insertion order, so the result is a set of keys rather than a sequence. An address given as a tuple is keyed by its text.

concurrency, retries and timeout_ms are overridable here, per call, so one large batch does not need a second client built to widen it. There is no cap on how many addresses one call takes; chunking them is this function's job.

lookup_domain(Client, Domain)

-spec lookup_domain(client(), binary() | string()) ->
                       {ok, internetdata_result:domain_result()} | {error, internetdata_error:error()}.

lookup_domain(Client, Domain, Options)

-spec lookup_domain(client(), binary() | string(), lookup_options()) ->
                       {ok, internetdata_result:domain_result()} | {error, internetdata_error:error()}.

What InternetData knows about one domain: whether it is registered and which record types it has on every plan, and on a paid one the records, its organization's IP ranges and whether it is disposable.

Domain is sent as given, and the API normalizes it; one it cannot read is a bad_request. Never cached. Options is lookup/3's.

my_entitlement(Client)

-spec my_entitlement(client()) ->
                        {ok, internetdata_result:entitlement()} | {error, internetdata_error:error()}.

my_entitlement(Client, Options)

-spec my_entitlement(client(), lookup_options()) ->
                        {ok, internetdata_result:entitlement()} | {error, internetdata_error:error()}.

What this client's key is entitled to, and how much of it has been used.

Named for what it answers rather than me, which sits one letter from my_ip/1 and means something quite different: one is which address you are calling FROM, the other is what the key you are calling WITH may spend.

Unlike a lookup there is no useful unauthenticated answer, so a client built without an API key gets an unauthorized error rather than a partial one.

Usage counts against the ALLOWANCE WINDOW - on a paid plan the anniversary of the subscription, not the calendar month and not the billing period, and on the free plan the UTC day - and it is the same number a lookup is gated on. hard_limit is null when we never stop serving, which is not the same as a limit of zero.

Deliberately NOT cached: the whole point is what has been spent, and a cached answer is a wrong one within seconds of the next request.

my_ip(Client)

-spec my_ip(client()) -> {ok, internetdata_result:result()} | {error, internetdata_error:error()}.

my_ip(Client, Options)

-spec my_ip(client(), lookup_options()) ->
               {ok, internetdata_result:result()} | {error, internetdata_error:error()}.

What every database says about the address this client is calling from.

The same answer lookup/2 would give for that address, at the same cost against your allowance. The address is the one our edge observed, so a call made through a proxy or a VPN reports the exit it left through - usually the point of asking.

Deliberately NOT cached. The cache is keyed by address, and which address this is IS the question: a machine that moves between networks would otherwise be told where it used to be.

new()

-spec new() -> client().

Build a client against production with no key.

new(Options)

-spec new(options()) -> client().

Build a client.

api_key is optional: without one a lookup is on Unlimited, the free plan, answering ip, is_bogon, the Tor and relay members, InternetData's own flags, location, asn, company, hostname and abuse with no daily or monthly cap. A batch needs a key on a paid plan, and the database endpoints a key with the db.download scope. Without one no authorization header is sent at all, and the oauth_* functions never send one. An empty or blank key is no key, and so are false, which is what os:getenv/1 answers for a variable that is not set, and nil, Elixir's System.get_env/1 answer for one. The key is trimmed, so one read from a file with its newline works; one still holding a control character raises {badarg, {api_key, control_character}}, naming the cause and not the key.

base_url defaults to https://api.internetdata.io, where every call but the oauth_* ones goes. Those go to the apex it sits under, api. dropped and api-<env>. becoming <env>., and to any other base URL as given.

timeout_ms is milliseconds from 1 to 4294967295, or infinity for no bound, retries an integer of 0 or more and concurrency an integer of 1 or more; anything else raises badarg here rather than failing every call.

The cache is per client and never shared, because two clients holding different keys are on different plans and so entitled to different fields. Unless cache is false this starts a process linked to the caller, which ends when the caller does, so build clients somewhere long lived and close/1 them when you are done.

oauth_authorization_url(Client, ClientId, RedirectUri, CodeChallenge)

-spec oauth_authorization_url(client(), binary() | string(), binary() | string(), binary() | string()) ->
                                 {ok, binary()} | {error, internetdata_error:error()}.

oauth_authorization_url(Client, ClientId, RedirectUri, CodeChallenge, Options)

-spec oauth_authorization_url(client(),
                              binary() | string(),
                              binary() | string(),
                              binary() | string(),
                              authorization_url_options()) ->
                                 {ok, binary()} | {error, internetdata_error:error()}.

The URL to open in the person's browser for the authorization code flow, from the challenge of oauth_create_pkce/0. Makes no request.

Once they decide, the server redirects to RedirectUri with a code for oauth_exchange_authorization_code/5 and the state given here, or with an error. scope, state and resource are left out when not given or empty. Every value is percent-encoded over UTF-8, leaving only A-Z a-z 0-9 - . _ ~ literal; an empty required value, or one with no UTF-8 form, answers bad_request. The client ID can also be the https URL of a client metadata document the app serves.

oauth_create_pkce()

-spec oauth_create_pkce() -> internetdata_oauth:pkce().

A fresh PKCE pair for one sign-in: 32 bytes from crypto's secure random source as a 43-character base64url verifier, its S256challenge, and the method. The challenge goes into the authorization URL, the verifier only to the exchange.

oauth_device_authorization(Client, ClientId)

-spec oauth_device_authorization(client(), binary() | string()) ->
                                    {ok, internetdata_oauth:device_authorization()} |
                                    {error, internetdata_error:error()}.

oauth_device_authorization(Client, ClientId, Options)

-spec oauth_device_authorization(client(), binary() | string(), device_authorization_options()) ->
                                    {ok, internetdata_oauth:device_authorization()} |
                                    {error, internetdata_error:error()}.

Start a device sign-in: show the person user_code and verification_uri, then call oauth_poll_device_token/3.

Client IDs are issued on request from support@internetdata.io. scope is one space-delimited string, sent as given; the server grants what the client may ask for and silently drops the rest.

oauth_exchange_authorization_code(Client, ClientId, Code, CodeVerifier, RedirectUri)

-spec oauth_exchange_authorization_code(client(),
                                        binary() | string(),
                                        binary() | string(),
                                        binary() | string(),
                                        binary() | string()) ->
                                           {ok, internetdata_oauth:token_response()} |
                                           {error, internetdata_error:error()}.

oauth_exchange_authorization_code(Client, ClientId, Code, CodeVerifier, RedirectUri, Options)

-spec oauth_exchange_authorization_code(client(),
                                        binary() | string(),
                                        binary() | string(),
                                        binary() | string(),
                                        binary() | string(),
                                        oauth_options()) ->
                                           {ok, internetdata_oauth:token_response()} |
                                           {error, internetdata_error:error()}.

Exchange the code a sign-in's redirect brought back for tokens, once. CodeVerifier is the verifier whose challenge went into the authorization URL, and RedirectUri that URL's, exactly.

Never retried: the server spends the code on first read, before it checks the verifier, so a retry could only be refused.

oauth_exchange_device_code(Client, ClientId, DeviceCode)

-spec oauth_exchange_device_code(client(), binary() | string(), binary() | string()) ->
                                    {ok, internetdata_oauth:token_response()} |
                                    {error, internetdata_error:error()}.

oauth_exchange_device_code(Client, ClientId, DeviceCode, Options)

-spec oauth_exchange_device_code(client(), binary() | string(), binary() | string(), oauth_options()) ->
                                    {ok, internetdata_oauth:token_response()} |
                                    {error, internetdata_error:error()}.

Exchange a device code for tokens, once. Until the person approves, this answers {error, #{error_code := <<"authorization_pending">>}}; oauth_poll_device_token/3 is the loop that waits for them.

Never retried: the server spends the code when it answers, so a retry after a lost success could only fail and lose the tokens. The answer carries apikey_id and apikey when the person picked a key.

oauth_exchange_refresh_token(Client, ClientId, RefreshToken)

-spec oauth_exchange_refresh_token(client(), binary() | string(), binary() | string()) ->
                                      {ok, internetdata_oauth:token_response()} |
                                      {error, internetdata_error:error()}.

oauth_exchange_refresh_token(Client, ClientId, RefreshToken, Options)

-spec oauth_exchange_refresh_token(client(), binary() | string(), binary() | string(), oauth_options()) ->
                                      {ok, internetdata_oauth:token_response()} |
                                      {error, internetdata_error:error()}.

Exchange a refresh token for a new pair. The token presented is spent, so keep the refresh_token this answers. Never retried; the answer may name the key in apikey_id but never carries apikey.

oauth_metadata(Client)

-spec oauth_metadata(client()) ->
                        {ok, internetdata_oauth:metadata()} | {error, internetdata_error:error()}.

oauth_metadata(Client, Options)

-spec oauth_metadata(client(), oauth_options()) ->
                        {ok, internetdata_oauth:metadata()} | {error, internetdata_error:error()}.

The authorization server's discovery document.

Every oauth_* call sends NO credential, whatever the client was built with, and works the same on a client built without a key. timeout_ms in Options bounds each attempt of this call alone.

oauth_pkce_challenge(Verifier)

-spec oauth_pkce_challenge(binary() | string()) -> binary().

The S256 challenge for a PKCE verifier: its SHA-256, as unpadded base64url.

oauth_poll_device_token(Client, ClientId, Device)

oauth_poll_device_token(Client, ClientId, Device, Options)

Wait for the person to approve a device sign-in, and answer its tokens.

Waits the device's interval seconds before EVERY exchange, the first included, and five seconds longer for good each time the server answers slow_down. A refusal answers error_code<<"access_denied">>; an expired code <<"expired_token">>, with no status when the device's expires_in ran out here first. Any other failure, a timeout or an outage included, ends the wait unchanged; calling again with the same device is safe until it expires.

It blocks the calling process until one of those outcomes. There is no cancellation handle, so run it in a process you can kill. timeout_ms bounds each exchange, never the whole wait.

oauth_register(Client, RedirectUris)

-spec oauth_register(client(), [binary() | string()]) ->
                        {ok, internetdata_oauth:client_registration()} |
                        {error, internetdata_error:error()}.

oauth_register(Client, RedirectUris, Options)

-spec oauth_register(client(), [binary() | string()], register_options()) ->
                        {ok, internetdata_oauth:client_registration()} |
                        {error, internetdata_error:error()}.

Register a client for the authorization code flow, for an app that cannot serve a Client ID Metadata Document, and get its client_id for oauth_authorization_url/5 and oauth_exchange_authorization_code/6.

Each redirect URI must be https on a public host name, or http on a loopback address, which then matches on any port; the server refuses any other with #{error_code := <<"invalid_redirect_uri">>}. client_name is shown to the person as the client's own claim. Nothing is kept until a person approves the client, so registering again costs nothing, and this is retried like a read. No URI at all, or an empty one, is bad_request with nothing sent.

oauth_revoke(Client, ClientId, Token)

-spec oauth_revoke(client(), binary() | string(), binary() | string()) ->
                      ok | {error, internetdata_error:error()}.

oauth_revoke(Client, ClientId, Token, Options)

-spec oauth_revoke(client(), binary() | string(), binary() | string(), oauth_options()) ->
                      ok | {error, internetdata_error:error()}.

Revoke an access or a refresh token. A refresh token ends the whole grant and every token it issued, which is how a machine signs out.

standings()

-spec standings() -> [binary()].

Every standing the pinned spec publishes for a family in database_list/1. A value added later still reads through as a binary.