Managing API keys securely

    An API key allows an application to access parts of your BitcoinVN account. Treat every key like a password: anyone who obtains it may be able to view account information or perform actions allowed by its permissions.

    Create and label a key

    Before creating a key, confirm that the intended main account or VIP sub-account is active.

    Then:

    1. Open Manage API keys.
    2. Select Generate new key.
    3. Copy the key to the application that will use it.
    4. Select Edit.
    5. Add a label that identifies the application or purpose.
    6. Choose its permissions and optional IP restrictions, then save.

    Use a separate key for each application so you can restrict or revoke one integration without affecting the others. Do not include secrets or personal information in the label.

    Choose the minimum permissions needed

    BitcoinVN provides two permission levels:

    • Read-only: Can view account data but cannot create orders.
    • Read & write: Can view account data and create orders.

    A read-and-write key can use your account balance to create orders and send the proceeds to a settlement destination. Anyone who obtains such a key may be able to withdraw your funds.

    Use read-only access unless the application genuinely needs to create orders.

    Restrict access by IP address

    You can restrict a key to specific IP addresses from its edit page:

    • Enter one IP address per line.
    • Add only the addresses used by the intended application.
    • Leave the field empty only if the application cannot use a stable IP address.

    Requests from other addresses will not be accepted while an IP restriction is configured. Update the list if the application’s address changes.

    Use the key with the API

    Send the key in the X-API-KEY request header:

    X-API-KEY: <your-api-key>

    Use the placeholder above only as an example. Never place a real key in public code, screenshots, support messages, browser-side applications, URLs, or logs.

    The interactive API documentation is available at bitcoinvn.io/api/doc.

    Understand sub-account context

    An API key remains associated with the account that was active when the key was created:

    • Keys created in the main account use the main account.
    • Keys created while a sub-account is active use that sub-account.

    Switching accounts on the website does not change an existing key. Verify the active account before generating it.

    Revoke or replace a key

    Open Manage API keys and select Revoke beside a key you no longer need. Revocation cannot be undone.

    If a key may have been exposed:

    1. Revoke it.
    2. Generate a replacement.
    3. Apply the required permissions and IP restrictions.
    4. Update the intended application.

    Never send an API key to BitcoinVN support or anyone claiming to represent BitcoinVN.

    Published: