Authentication with the Block-Auth API

You'll need to authenticate your requests to access any of the endpoints in the Block-Auth API. In this guide, we’ll look at how authentication works. Block-Auth offers one way authenticate your API requests with an OAuth2 token.

Basic authentication

With basic authentication, you use your api_key and a SHA256 hash of your api_secret to authenticate your HTTP requests. Unless you have a very good reason, you probably shouldn't use basic auth. Here's how to authenticate using cURL:

curl --location 'https://api.block-auth.io/api/signin' \
--header 'Content-Type: application/json' \
--data '{
    "apiKey": "your_api_key",
    "apiSecret": "SHA256_hash_of_your_api_secret"
}'

You should replace your_api_key and your_api_secret with your actual API key and secret. After this the response for /api/signin will be:

{
    "success": true,
    "message": {
        "accessToken": "response_access_token",
        "refreshToken": "response_refresh_token"
    }
}

Please don't commit your Block-Auth password to GitHub!

Try calculating SHA-256 hash here:

Introduce your secret and calculate the SHA-256 hash in the field below:

Refresh token

The refresh token you receive in the authentication response can be used to obtain a new access token when the current one expires. This allows you to maintain authentication without requiring the user to log in again.

To refresh your token, make a POST request to the api/refresh endpoint, including param refreshToken in the request body, and you will again receive the same response that you get with the call from /api/signin

OAuth2 with bearer token

We follow the standard down RFC 6750, the recommended way to authenticate with the Block-Auth API is by using OAuth2. When establishing a connection using OAuth2, you will need your access token — you will find it in the Block-Auth dashboard under API settings. Here's how to add the token to the request header using cURL:

curl --location 'https://api.block-auth.io/api/sign?address=0x7F8556ee2a47D3d8294A69714E54D6C4894046D8' \
--header 'Authorization: Bearer your_access_token_here' \
--data ''

You should replace your_access_token_here with your actual access token. After this the response for /api/sign can be ok or not. If everything is ok, you will get a response with a status code of 200 OK, if something goes wrong, you will get a response with a status code of 401 Unauthorized, review the response body for more information. Here are some examples of possible responses:

{
    "success": true,
    "message": {
        "did": "0xCE0aF99d5F305373b2aB932fbee196785Deb9b4d",
        "signedNonce": 1,
        "signedAt": "2024-04-05 17:18:26",
        "signedExpiredAt": "2024-04-05 17:51:33"
    }
}

Always keep your token safe and reset it if you suspect it has been compromised.

Using an SDK

If you use one of our official SDKs, you won't have to worry about any of the above — SDK will fetch your access token automatically for you. Just take api key + api secret from the Block-Auth dashboard under API settings, and the client library will take care of the rest. All the client libraries use OAuth2 behind the scenes.