Authentication with Cobo OAuth

​

Cobo OAuth vs Cobo Auth

• If you are developing Cobo Portal Apps for installation and use across different organizations, use Cobo OAuth to authenticate your API requests.
• If you are developing other types of apps to access data and resources within your own organization, use Cobo Auth instead. For more details about Cobo Auth, refer to Authentication with Cobo Auth.

​

With the WaaS SDK

from cobo_waas2 import Configuration, ApiClient, WalletsApi

configuration = Configuration(
    # Use `https://api.dev.cobo.com/v2` for the development environment, or `https://api.cobo.com/v2` for the production environment.
    host="https://api.dev.cobo.com/v2",
    # Replace `<APP_PRIVATE_KEY>` with the private key of your app key.
    api_private_key="<APP_PRIVATE_KEY>",
)

client = ApiClient(configuration=configuration)
# Replace `{ORG_ACCESS_TOKEN}` with the Org Access Token.
client.set_default_header("AUTHORIZATION", f"Bearer {ORG_ACCESS_TOKEN}")

• To learn how to generate an app key, see Generate an app key.
• To learn how to get and use Org Access Tokens, refer to Org Access Tokens.

​

Without the WaaS SDK

headers = {
    // Replace `{ORG_ACCESS_TOKEN}` with the Org Access Token.
    "Authorization": Bearer {ORG_ACCESS_TOKEN},
    // Replace `<APP_PUBLIC_KEY>` with the public key of your app key.
    "Biz-Api-Key": {APP_PUBLIC_KEY}.hex(),
    // Replace `{Nonce}` with the current time in Unix timestamp format, measured in milliseconds.
    // This value must be the same as the value of the `TIMESTAMP` field in the API signature.
    "Biz-Api-Nonce": {Nonce},
    // Replace `{YOUR_API_SIGNATURE}` with the calculated API signature.
    "Biz-Api-Signature": {YOUR_API_SIGNATURE}.hex(),
}

• To learn how to generate an app key, see Generate an app key.
• To learn how to get and use Org Access Tokens, refer to Org Access Tokens.
• To learn how to calculate the API signature using your app key, refer to Calculate an API signature.

​

Generate an app key

• The public key will be used in the manifest file. For more information, refer to Configure the manifest file.
• The private key will be used to authenticate API requests to the WaaS service.

​

Use Cobo CLI

1. Install Cobo CLI if you haven’t. For more information, refer to Install Cobo CLI.
2. In a terminal window, run the following command to generate a key pair.
   cobo keys generate
   

​

Use OpenSSL

# Generate a private key and save it in the `private.key.pem` file.
openssl genpkey -algorithm ed25519 -out private_key.pem
# Extract the public key from the private key and save it in the `public.key.pem` file.
openssl pkey -in private_key.pem -pubout -out public_key.pem
# Export the private key in hexadecimal format.
openssl pkey -in private_key.pem -text | grep 'priv:' -A 3 | tail -n +2 | tr -d ':\n '
# Export the public key in hexadecimal format.
openssl pkey -pubin -in public_key.pem -text | grep 'pub:' -A 3 | tail -n +2 | tr -d ':\n '

​

Use a Python library

1. Install the ed25519 Python library. In a terminal window, run the following command:
   pip install ed25519
   
2. Generate a key pair. Import the function from the Python library to generate a key pair as follows:
   from ed25519.keys import create_keypair
   
   # Create a key pair.
   sk, vk = create_keypair()
   # Print the private key in hexadecimal format.
   print("private key:", sk.to_seed().hex())
   # Print the public key in hexadecimal format.
   print("public key:", vk.to_bytes().hex())
   

​

Calculate an API signature

1. First, concatenate a string based on your request as follows: str_to_sign = {METHOD}|{PATH}|{TIMESTAMP}|{PARAMS}|{BODY}

   Field	Description	Example
   METHOD	The HTTP method.	GET
   PATH	The API endpoint.	/v2/transactions/transfer
   TIMESTAMP	The current time in Unix timestamp format, measured in milliseconds. This value must be the same as the nonce in the request header.	1718587017026
   PARAMS	(If applicable) The query parameters.	chain_id=ETH&limit=10
   BODY	(If applicable) The raw request body in string format.	{"name":"Default","wallet_subtype":"Asset","wallet_type":"Custodial"}

2. Use the hashlib library to perform SHA-256 hashing twice on the string as follows:
   import hashlib
   
   content_hash = hashlib.sha256(hashlib.sha256(str_to_sign.encode()).digest()).digest()
   
3. Use the private key of your app key to sign the string as follows:
   # Replace `api_secret` with your private key.
   sk = ed25519.SigningKey(sk_s=bytes.fromhex(api_secret))
   # Sign the hashed message
   signature = sk.sign(content_hash)