API usage

Introduction

The data collected for the 2fa.directory website is also available as JSON files in order to enable developers to use it in their own programs. It is recommended to use the API with the highest version number, since older versions might not include all available information.

Caching

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 large traffic cases.

Avoid downloading unnecessary data

If you only intent on using a specific dataset, like all sites supporting RFC-6238, we recommend that you use the URI which lists just that. See URIs for a list of available paths. The smaller the better.

Version 3

URIs

CoverageUnsigned fileSigned file
All siteshttps://2fa.directory/api/v3/all.jsonhttps://2fa.directory/api/v3/all.json.sig
All 2FA-supporting siteshttps://2fa.directory/api/v3/tfa.jsonhttps://2fa.directory/api/v3/tfa.json.sig
SMShttps://2fa.directory/api/v3/sms.jsonhttps://2fa.directory/api/v3/sms.json.sig
Phone callshttps://2fa.directory/api/v3/call.jsonhttps://2fa.directory/api/v3/call.json.sig
Email 2FAhttps://2fa.directory/api/v3/email.jsonhttps://2fa.directory/api/v3/email.json.sig
non-U2F hardware 2FA tokenshttps://2fa.directory/api/v3/custom-hardware.jsonhttps://2fa.directory/api/v3/custom-hardware.json.sig
U2F hardware tokenshttps://2fa.directory/api/v3/u2f.jsonhttps://2fa.directory/api/v3/u2f.json.sig
RFC-6238 (TOTP)https://2fa.directory/api/v3/totp.jsonhttps://2fa.directory/api/v3/totp.json.sig
non-RFC-6238 software 2FAhttps://2fa.directory/api/v3/custom-software.jsonhttps://2fa.directory/api/v3/custom-software.json.sig

Elements

KeyValueAlways definedDescription
domainhostname:heavy_check_mark:The domain name of the service
imgString Image name used. If this is not defined, the image name is domain.svg
urlURL URL of the site. If this is not defined, the url is https://domain
tfaArray<String> Array containing all supported 2FA methods
documentationURL URL to documentation page
recoveryURL URL to recovery documentation page
notesString Text describing any discrepancies in the 2FA implementation
contactObject Object containing contact details. See table below for elements
regionsarray<String> Array containing ISO 3166-1 country codes of the regions in which the site is available. If the site is available everywhere apart from a specific region, that region will be prefixed by a - symbol
additional-domainsArray<hostname> Array of domains that the site exists at in addition to the main domain listed in the domain field.
custom-(software|hardware)Array<String> Array of custom software/hardware methods that the site supports. Only present if the tfa element contains one of these 2FA types
keywordsArray<String>:heavy_check_mark:Array of categories to which the site belongs

Contact Object Elements

|Key|Value|Always defined|Description| |—|—–|—————|———–| |twitter|String||Twitter handle| |facebook|String||Facebook page name| |email|String||Email address to support| |language|String||Lowercase ISO 639-1 language code for the site if it is not in English|

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 (Deprecated) :warning:

URIs

CoverageUnsigned fileSigned file
All siteshttps://2fa.directory/api/v2/all.jsonhttps://2fa.directory/api/v2/all.json.sig
All 2FA-supporting siteshttps://2fa.directory/api/v2/tfa.jsonhttps://2fa.directory/api/v2/tfa.json.sig
SMShttps://2fa.directory/api/v2/sms.jsonhttps://2fa.directory/api/v2/sms.json.sig
Phone callshttps://2fa.directory/api/v2/phone.jsonhttps://2fa.directory/api/v2/phone.json.sig
Email 2FAhttps://2fa.directory/api/v2/email.jsonhttps://2fa.directory/api/v2/email.json.sig
non-U2F hardware 2FA tokenshttps://2fa.directory/api/v2/hardware.jsonhttps://2fa.directory/api/v2/hardware.json.sig
U2F hardware tokenshttps://2fa.directory/api/v2/u2f.jsonhttps://2fa.directory/api/v2/u2f.json.sig
RFC-6238 (TOTP)https://2fa.directory/api/v2/totp.jsonhttps://2fa.directory/api/v2/totp.json.sig
non-RFC-6238 software 2FAhttps://2fa.directory/api/v2/proprietary.jsonhttps://2fa.directory/api/v2/proprietary.json.sig

Elements

KeyValueAlways definedDescription
urlURL:heavy_check_mark:URL to the main page of the site/service
imgString:heavy_check_mark:Image name used
tfaArray<String> Array containing all supported 2FA methods
docURL URL to documentation page
exceptionString Text describing any discrepancies in the 2FA implementation
twitterString Twitter handle
facebookString Facebook page name
email_addressString Email address to support

Example website with 2FA enabled

{
  "Category name": {
    "Website name": {
      "url": "https://example.com/",
      "img": "example.png",
      "tfa": [
        "sms",
        "phone",
        "hardware",
        "totp",
        "proprietary",
        "u2f"
      ],
      "doc": "https://example.com/documention/enable-2fa/",
      "exception": "Text describing any discrepancies in the 2FA implementation."
    }
  }
}

Example website with 2FA disabled

{
  "Category name": {
    "Website name": {
      "url": "https://example.com/",
      "img": "example.png",
      "twitter": "example",
      "facebook": "example",
      "email_address": "[email protected]"
    }
  }
}

Version 1 (Deprecated) :warning:

URIs

CoverageUnsigned fileSigned file
All siteshttps://2fa.directory/api/v1/data.jsonhttps://2fa.directory/api/v1/data.json.sig

Elements

KeyValueAlways definedDescription
urlURL:heavy_check_mark:URL to the main page of the site/service
imgString:heavy_check_mark:Image name used
tfaBoolean:heavy_check_mark:2FA support
smsBoolean SMS token support
phoneBoolean Phone call support
emailBoolean Email token support
softwareBoolean Software token support (including RFC-6238)
hardwareBoolean Hardware token support (including U2F tokens)
docURL URL to documentation page
exceptionsObject<“text”: String> Object containing the key text describing any discrepancies in the 2FA implementation
twitterString Twitter handle
facebookString Facebook page name
email_addressString Email address to support

Example website with 2FA disabled

{
  "Category name": {
    "Website name": {
      "name": "Website name",
      "url": "https://example.com/",
      "img": "example.png",
      "tfa": false
    }
  }
}

Example website with 2FA enabled

{
  "Category name": {
    "Website name": {
      "name": "Website name",
      "url": "https://example.com/",
      "img": "example.png",
      "tfa": true,
      "sms": true,
      "phone": true,
      "email": true,
      "software": true,
      "hardware": true,
      "doc": "https://example.com/documention/enable-2fa/",
      "exceptions": {
        "text": "Text describing any discrepancies in the 2FA implementation."
      }
    }
  }
}

If a website only supports some 2FA methods, the unsupported 2FA methods won’t be listed (i.e. NULL).