API usage

Introduction

The data collected for the 2FA Directory website is also available as JSON files for developers to use in their programs.

Supported versions

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.

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 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 by 2factorauth.

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.

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

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

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.

Elements

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.

Examples

Below are examples of what an entry can look like in API version 4.

Example website with 2FA enabled

{
  "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

{
  "example.com": {}
}

Version 3 {#v3}

URIs

Elements

Contact Object Elements

Example website with 2FA enabled

[
  [
    "Site Name",
    {
      "domain": "example.com",
      "additional-domains": [
        "example.net"
      ],
      "tfa": [
        "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>",
      "keywords": [
        "keyword1",
        "keyword2"
      ]
    }
  ]
]

Example website with 2FA disabled

[
  [
    "Site Name", 
    {
      "domain": "example.com",
      "contact": {
        "twitter": "example",
        "facebook": "example",
        "email": "[email protected]"
      },
      "keywords": [
        "keyword1",
        "keyword2"
      ]
    }
  ]
]

Version 2 {#v2}

API version 2 is no longer available. Please upgrade to a supported version.

Version 1 {#v1}

API version 1 is no longer available. Please upgrade to a supported version.