v1

Bine Auth protocol based on EIP-712

v1 Auth API is deprecated and will be removed in the future. Use v2 Auth API instead.

Introduction

The Bine v1 API offers an Ethereum-based authentication mechanism that allows users to authenticate using their Ethereum wallets. This documentation covers the authentication process in a language-agnostic manner focusing on GraphQL.

Prerequisites

• You must have an Ethereum wallet, like MetaMask or WalletConnect.

Authentication Process

The authentication is split into two major steps: fetching data to sign and then obtaining an access token using the signed data.

Step 1: Retrieve Data to Sign

Firstly, clients will need to fetch data that will be signed by their Ethereum wallet to ensure authenticity.

Query:

query GetSignData($address: String!) {
    signData(address: $address) {
        primaryType
        types {
            AuthMessage {
                name
                type
            }
            EIP712Domain {
                name
                type
            }
        }
        domain {
            name
            version
            chainId
            verifyingContract
        }
        message {
            address
            noonce
        }
    }
}

Response:

A typical response will include the primary type, the types for the AuthMessage and EIP712Domain, domain details, and the message containing the user's address and a nonce.

Step 2: Sign the Data with Your Ethereum Wallet

Once you have fetched the data, use your Ethereum wallet to sign the given message. This step would be specific to the Ethereum wallet interface you are using.

Step 3: Obtain Access Token Using Signed Data

After obtaining the signed data, you will send it back to the server, along with the original nonce, to verify the signature and receive an access token in return.

Mutation:

mutation GetAuthToken($address: String!, $noonce: Int!, $signature: String!) {
    getAccessToken(address: $address, noonce: $noonce, salt: null, signature: $signature) {
        __typename
        ... on Token {
            accessToken
        }
        ... on Error {
            message
        }
    }
}

Variables:

{
    "address": "<Ethereum_Address>",
    "signature": "<Signed_Data>",
    "noonce": <Nonce_Value>
}

Response:

A successful response will provide an access token. If there are errors in the process, the mutation will return error messages indicating the issues.

Error Handling

• If there's a problem with the signature, nonce, or any other aspect of the process, the API will return a Error type with an appropriate error message.

Tips & Recommendations

• Always keep your Ethereum wallet's private keys safe. Do not share them or expose them to any service.

• Use secured channels when communicating with the API.

Further Reading & Resources

• To understand more about Ethereum and its cryptographic signing, refer to Ethereum's official documentation.

• For a deeper dive into GraphQL and its principles, visit the GraphQL official website.