Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

List API v4 #64

Merged
merged 11 commits into from
Aug 3, 2024
Merged

List API v4 #64

Changes from 9 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
8167102
List API v4
Carlgo11 Aug 1, 2024
ecb18f7
Merge branch 'master' into add-api-v4
Carlgo11 Aug 1, 2024
caf67dd
Merge code suggestions
Carlgo11 Aug 2, 2024
d723a66
Remove inadvertent new line
Carlgo11 Aug 2, 2024
d288dad
Merge branch 'master' into add-api-v4
Carlgo11 Aug 2, 2024
e6426b8
Remove Contact object in APIv4
Carlgo11 Aug 2, 2024
9f9f48d
Make all links reference styled
Carlgo11 Aug 2, 2024
b64c95d
Remove '/' from v3 URIs
Carlgo11 Aug 2, 2024
935c056
empty commit
Carlgo11 Aug 3, 2024
fb6ce65
Update api.md
Carlgo11 Aug 3, 2024
7a0fb37
Update api.md
Carlgo11 Aug 3, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
196 changes: 178 additions & 18 deletions content/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,31 +4,155 @@ title: API usage
---
## Introduction

The data collected for the [2FA Directory](https://2fa.directory) website is also available as JSON files to enable developers to use it in their programs. The API with the highest version number is recommended since older versions might not include all available information.
The data collected for the [2FA Directory][site_url] website is also available as JSON files for developers to use in their programs.

### Caching
## Supported versions

If you intend to query our JSON files often and with a lot of traffic, you may be blocked by Cloudflare, our reverse proxy provider. We therefore recommend that you cache the files locally for any significant traffic cases.
The table below provides the End of Life (EOL) dates for different 2FA Directory API versions. Please refer to this table to ensure you are using a supported version.

### Avoid downloading unnecessary data
| Version | Supported |
|:----------------:|:----------------------------:|
| [Version 4](#v4) | Yes |
| [Version 3](#v3) | Yes |
| [Version 2](#v2) | Unsupported since 2023-08-01 |
| [Version 1](#v1) | Unsupported since 2023-07-01 |

If you only intend to use a specific dataset, like all sites supporting RFC-6238, we recommend using the URI which lists _just_ that. See [URIs](#uris) for available paths. The smaller, the better.
## Things to note

When using the 2FA Directory data, there are a few important considerations to keep in mind to ensure compliance and optimal performance.

#### Attribution

The data for the 2FA Directory is licensed under an [MIT license][license] which requires attribution when using the data.
If the data collected from the 2FA Directory is visible to your users, please provide attribution. This helps acknowledge the source and supports the ongoing maintenance of the directory.
At a minimum, please include the following attribution:

> Data sourced from [2FA Directory][site_url] by [2factorauth][repo_url].
hkamran80 marked this conversation as resolved.
Show resolved Hide resolved

#### Caching

It is advisable to cache the files locally to avoid potential service interruptions, especially if you intend to query our JSON files frequently or generate significant traffic. Cloudflare, our reverse proxy provider, may block excessive traffic, so local caching ensures your access remains uninterrupted and reduces server load.

#### Avoid downloading unnecessary data

It is recommended that you download only the specific datasets you need to maximize efficiency and minimize data transfer. For example, if you only require information about sites supporting TOTP (RFC-6238), use the URI that lists only those sites. This approach conserves bandwidth and accelerates data processing.

#### Signed Files

All JSON files provided by the 2FA Directory are also available as PGP-signed files. These files are signed by 2factorauth to ensure their integrity and authenticity. Using signed files allows you to verify that the data has not been tampered with and is indeed from 2factorauth.

The public key used for signing is published as a CERT record on `security.2fa.directory`. In the event that the GitHub repository, domain name, or build process is compromised, the key will be missing or revoked.

## FAQ

### How often is the data updated?

Changes to the data are reflected within a minute of being made on the GitHub repository. The frequency of changes in the GitHub repository varies from several per day to a few per week.

### How do I verify the PGP signatures?

Using GPG, you can download the public key of our signing key.

```bash
gpg --auto-key-locate cert --locate-keys [email protected]
```

You can then verify a `.json.sig`-file using:

```bash
gpg --verify <file>.sig <file>
```

## Version 4 {#v4}

Version 4 of the 2FA Directory JSON files focuses on only outputting data relevant to third-party applications.
We have removed elements such as service names, icon paths, and service categories.

### URIs

The following JSON files are available for Version 4, each serving different 2FA methods and data requirements.

| Coverage | Unsigned File | PGP Signed File |
|-----------------------------|----------------------------------------------------|------------------------------------------------------------|
| All sites | [v4/all.json][v4/all.json] | [v4/all.json.sig][v4/all.json.sig] |
| SMS 2FA | [v4/sms.json][v4/sms.json] | [v4/sms.json.sig][v4/sms.json.sig] |
| Email 2FA | [v4/email.json][v4/email.json] | [v4/email.json.sig][v4/email.json.sig] |
| Non-U2F hardware 2FA tokens | [v4/custom-hardware.json][v4/custom-hardware.json] | [v4/custom-hardware.json.sig][v4/custom-hardware.json.sig] |
| U2F hardware tokens | [v4/u2f.json][v4/u2f.json] | [v4/u2f.json.sig][v4/u2f.json.sig] |
| TOTP (RFC-6238) | [v4/totp.json][v4/totp.json] | [v4/totp.json.sig][v4/totp.json.sig] |
| Non-RFC-6238 software 2FA | [v4/custom-software.json][v4/custom-software.json] | [v4/custom-software.json.sig][v4/custom-software.json.sig] |

### Elements
Carlgo11 marked this conversation as resolved.
Show resolved Hide resolved

The JSON files contain various elements that provide detailed information about the 2FA implementations of different sites.
The availability of the elements depends on their presence in the source data.

| Key | Type | Description |
|-----------------|----------------|---------------------------------------------------------------------------------------------------------------------------|
| methods | Array\<String> | Array containing all supported 2FA methods |
| documentation | URL | URL to documentation page |
| recovery | URL | URL to recovery documentation page |
| notes | String | Text describing any discrepancies in the 2FA implementation |
| custom-hardware | Array\<String> | Array of custom hardware methods that the site supports. Only present if the `methods` element contains "custom-hardware" |
| custom-software | Array\<String> | Array of custom software methods that the site supports. Only present if the `methods` element contains "custom-software" |

### Examples

Below are examples of what an entry can look like in API version 4.
One entry for a site that supports 2FA and one that doesn't.
Carlgo11 marked this conversation as resolved.
Show resolved Hide resolved

#### Example website with 2FA enabled

```JSON
{
"example.com": {
"methods": [
"sms",
"call",
"email",
"totp",
"u2f",
"custom-software",
"custom-hardware"
],
"custom-software": [
"Authy"
],
"documentation": "<link to site TFA documentation>",
"recovery": "<link to site TFA recovery documentation>"
}
}
```

#### Example website with 2FA disabled

```JSON
{
"example.com": {
"contact": {
"twitter": "example",
"facebook": "example",
"email": "[email protected]"
}
}
Carlgo11 marked this conversation as resolved.
Show resolved Hide resolved
}
```

## Version 3 {#v3}

### URIs

| Coverage | Unsigned File | PGP Signed File |
|-----------------------------|-------------------------------------------------------------------------------|---------------------------------------------------------------------------------------|
| All sites | [/v3/all.json](https://api.2fa.directory/v3/all.json) | [/v3/all.json.sig](https://api.2fa.directory/v3/all.json.sig) |
| All 2FA-supporting sites | [/v3/tfa.json](https://api.2fa.directory/v3/tfa.json) | [/v3/tfa.json.sig](https://api.2fa.directory/v3/tfa.json.sig) |
| SMS | [/v3/sms.json](https://api.2fa.directory/v3/sms.json) | [/v3/sms.json.sig](https://api.2fa.directory/v3/sms.json.sig) |
| Phone calls | [/v3/call.json](https://api.2fa.directory/v3/call.json) | [/v3/call.json.sig](https://api.2fa.directory/v3/call.json.sig) |
| Email 2FA | [/v3/email.json](https://api.2fa.directory/v3/email.json) | [/v3/email.json.sig](https://api.2fa.directory/v3/email.json.sig) |
| non-U2F hardware 2FA tokens | [/v3/custom-hardware.json](https://api.2fa.directory/v3/custom-hardware.json) | [/v3/custom-hardware.json.sig](https://api.2fa.directory/v3/custom-hardware.json.sig) |
| U2F hardware tokens | [/v3/u2f.json](https://api.2fa.directory/v3/u2f.json) | [/v3/u2f.json.sig](https://api.2fa.directory/v3/u2f.json.sig) |
| RFC-6238 (TOTP) | [/v3/totp.json](https://api.2fa.directory/v3/totp.json) | [/v3/totp.json.sig](https://api.2fa.directory/v3/totp.json.sig) |
| non-RFC-6238 software 2FA | [/v3/custom-software.json](https://api.2fa.directory/v3/custom-software.json) | [/v3/custom-software.json.sig](https://api.2fa.directory/v3/custom-software.json.sig) |
| Coverage | Unsigned File | PGP Signed File |
|-----------------------------|----------------------------------------------------|------------------------------------------------------------|
| All sites | [v3/all.json][v3/all.json] | [v3/all.json.sig][v3/all.json.sig] |
| All 2FA-supporting sites | [v3/tfa.json][v3/tfa.json] | [v3/tfa.json.sig][v3/tfa.json.sig] |
| SMS | [v3/sms.json][v3/sms.json] | [v3/sms.json.sig][v3/sms.json.sig] |
| Phone calls | [v3/call.json][v3/call.json] | [v3/call.json.sig][v3/call.json.sig] |
| Email 2FA | [v3/email.json][v3/email.json] | [v3/email.json.sig][v3/email.json.sig] |
| non-U2F hardware 2FA tokens | [v3/custom-hardware.json][v3/custom-hardware.json] | [v3/custom-hardware.json.sig][v3/custom-hardware.json.sig] |
| U2F hardware tokens | [v3/u2f.json][v3/u2f.json] | [v3/u2f.json.sig][v3/u2f.json.sig] |
| RFC-6238 (TOTP) | [v3/totp.json][v3/totp.json] | [v3/totp.json.sig][v3/totp.json.sig] |
| non-RFC-6238 software 2FA | [v3/custom-software.json][v3/custom-software.json] | [v3/custom-software.json.sig][v3/custom-software.json.sig] |

### Elements

Expand Down Expand Up @@ -114,8 +238,44 @@ If you only intend to use a specific dataset, like all sites supporting RFC-6238

## Version 2 {#v2}

API version 2 is no longer available. Please upgrade to [version 3](#v3) if you use this version.
API version 2 is no longer available. Please upgrade to a [supported version](#supported-versions).

## Version 1 {#v1}

API version 1 is no longer available. Please upgrade to [version 3](#v3) if you use this version.
API version 1 is no longer available. Please upgrade to a [supported version](#supported-versions).

[license]: https://github.com/2factorauth/twofactorauth/blob/master/LICENSE.md
[site_url]: https://2fa.directory/
[repo_url]: https://github.com/2factorauth/
[v3/all.json]: https://api.2fa.directory/v3/all.json
[v3/all.json.sig]: https://api.2fa.directory/v3/all.json.sig
[v3/tfa.json]: https://api.2fa.directory/v3/tfa.json
[v3/tfa.json.sig]: https://api.2fa.directory/v3/tfa.json.sig
[v3/sms.json]: https://api.2fa.directory/v3/sms.json
[v3/sms.json.sig]: https://api.2fa.directory/v3/sms.json.sig
[v3/call.json]: https://api.2fa.directory/v3/call.json
[v3/call.json.sig]: https://api.2fa.directory/v3/call.json.sig
[v3/email.json]: https://api.2fa.directory/v3/email.json
[v3/email.json.sig]: https://api.2fa.directory/v3/email.json.sig
[v3/custom-hardware.json]: https://api.2fa.directory/v3/custom-hardware.json
[v3/custom-hardware.json.sig]: https://api.2fa.directory/v3/custom-hardware.json.sig
[v3/u2f.json]: https://api.2fa.directory/v3/u2f.json
[v3/u2f.json.sig]: https://api.2fa.directory/v3/u2f.json.sig
[v3/totp.json]: https://api.2fa.directory/v3/totp.json
[v3/totp.json.sig]: https://api.2fa.directory/v3/totp.json.sig
[v3/custom-software.json]: https://api.2fa.directory/v3/custom-software.json
[v3/custom-software.json.sig]: https://api.2fa.directory/v3/custom-software.json.sig
[v4/all.json]: https://api.2fa.directory/v4/all.json
[v4/all.json.sig]: https://api.2fa.directory/v4/all.json.sig
[v4/sms.json]: https://api.2fa.directory/v4/sms.json
[v4/sms.json.sig]: https://api.2fa.directory/v4/sms.json.sig
[v4/email.json]: https://api.2fa.directory/v4/email.json
[v4/email.json.sig]: https://api.2fa.directory/v4/email.json.sig
[v4/custom-hardware.json]: https://api.2fa.directory/v4/custom-hardware.json
[v4/custom-hardware.json.sig]: https://api.2fa.directory/v4/custom-hardware.json.sig
[v4/u2f.json]: https://api.2fa.directory/v4/u2f.json
[v4/u2f.json.sig]: https://api.2fa.directory/v4/u2f.json.sig
[v4/totp.json]: https://api.2fa.directory/v4/totp.json
[v4/totp.json.sig]: https://api.2fa.directory/v4/totp.json.sig
[v4/custom-software.json]: https://api.2fa.directory/v4/custom-software.json
[v4/custom-software.json.sig]: https://api.2fa.directory/v4/custom-software.json.sig
Loading