API Authentication

We offer three authentication options for accessing the Coinbase API:

Method Best For
API Key + Secret Accessing your own account.
OAuth2 Lets others grant your application full or partial access to their account.
API Key deprecated Accessing your own account.

API Key + Secret We recommend this option if you only need to access your own account.

How to start

You can create a new API key and set what actions are permitted when making requests with it in your account settings. A list of permissions and what they give access to can be found on the permissions page.

Example

Request:

GET /api/v1/account/balance HTTP/1.1
Accept: */*
User-Agent: Ruby
ACCESS_KEY: <YOUR-API-KEY>
ACCESS_SIGNATURE: <YOUR-COMPUTED-SIGNATURE>
ACCESS_NONCE: <YOUR-UPDATED-NONCE>
Connection: close
Host: coinbase.com

Response:

{"amount"=>"50.00000000", "currency"=>"BTC"}

The ACCESS_KEY header is simply your API key.

The ACCESS_SIGNATURE header is a HMAC-SHA256 hash of the nonce concatentated with the full URL and body of the HTTP request, encoded using your API secret.

The nonce is a positive integer number that must increase with every request you make. The nonce parameter can be included in one of three ways:

  • As a ACCESS_NONCE header in your requests. Example.
  • As a GET parameter in the URL. Example.
  • As a root-level parameter in your JSON POST requests

This scheme is generally known as "HMAC authentication" (see wikipedia article). Here are some examples of code, making simple API calls:

  • Python example
  • Ruby example
  • Java example

Create a new API Key   (sign in required)

 

OAuth2 Authentication We recommend this option if your application needs to access other user's accounts.

The OAuth2 protocol allows third parties to grant your application full or partial access to their account, without sharing their api key or password. It is a slightly more complex integration than the api key authentication method, but is more flexible. OAuth2 works well for web applications, as well as desktop and mobile applications.

There are good OAuth2 client libraries in most languages due to its widespread use by companies like Google and Facebook.


Registration

To get started you should create an OAuth2 application and obtain a client_id and client_secret.

You will also be prompted to set a redirect_uri which is a url on your website. If you are developing a desktop or mobile application, see the section below on what redirect_uri to use.

Two-legged OAuth2 requires the user to enter their username and password, and is deprecated. It will be removed on Feb 1st, 2014.

Three-legged OAuth2 requires the user to authorize your app on a browser page after logging into their account. To authenticate a user with three-legged OAuth2:

  • Use the client_id and client_secret you obtained during registration to generate an authorize_url and redirect the user to this url. Optionally include scope or meta parameters to request a specific set of permissions.
  • If the user authorizes your app, they will be returned to the redirect_uri you set during registration (with a code param in the url).
  • Use the code param in the url to generate an access_token
  • Use this access_token to make API calls on the user's behalf.

Examples

Ruby example:

require 'oauth2'
redirect_uri = 'http://www.yourwebsite.com/oauth2/callback' # this must match the url you set during registration
client = OAuth2::Client.new(CLIENT_ID, CLIENT_SECRET, site: 'https://coinbase.com')
`open "#{client.auth_code.authorize_url(redirect_uri: redirect_uri)}"`
print "Enter the code returned in the URL: "
code = STDIN.readline.chomp
token = client.auth_code.get_token(code, redirect_uri: redirect_uri)
puts JSON.parse(token.get('/api/v1/account/balance').body)

The following paths are used for requesting tokens (using a code, email and password, or refresh token):

GET    https://coinbase.com/oauth/authorize     display authorization form
POST   https://coinbase.com/oauth/token         endpoint for requesting the token, include a grant
                                                type of (authorization code, resource owner
                                                credentials, client credentials, or refresh token)
            

Here is a sample flow that your app might go through:

# Redirect the user to this page
https://coinbase.com/oauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_CALLBACK_URL

# If the user accepts, they will be redirected to:
YOUR_CALLBACK_URL?code=CODE

# Initiate a POST request to get the access token
https://coinbase.com/oauth/token?grant_type=authorization_code&code=CODE&redirect_uri=YOUR_CALLBACK_URL&client_id=CLIENT_ID&client_secret=CLIENT_SECRET

# Response containing the 'access_token'
{
    "access_token": "...",
    "refresh_token": "...",
    "token_type": "bearer",
    "expire_in": 7200,
    "scope": "universal"
}

# Now you can use the 'access_token' to initiate authenticated requested
https://coinbase.com/api/v1/account/balance?access_token=...

# Response
{"amount"=>"50.00000000", "currency"=>"BTC"}
            

Note that Two-Legged OAuth2 is deprecated and will be removed on Feb 1st, 2014.

To authenticate with two-legged OAuth2:

  • Use the client_id and client_secret you obtained during registration along with an email and password to generate an access_token. Optionally include a scope parameter to request a specific set of permissions.
  • Use this access_token to make API calls on the user's behalf.

Ruby example:

require 'oauth2'
client = OAuth2::Client.new(CLIENT_ID, CLIENT_SECRET, site: "https://coinbase.com")
access_token = client.password.get_token('[email protected]', 'test123!')
puts JSON.parse(access_token.get('/api/v1/account/balance').body)

Note that if you (or the user in question) has two-factor authentication turned on you will also need to pass the token from their cell phone to authenticate the user. Since not all OAuth2 client libraries have support for passing additional fields, we've combined the token field with the username field (separated by a comma).

For example, to pass the two-factor token 1234567 in the previous example you would use:

access_token = client.password.get_token('[email protected],1234567', 'test123!')

Access Tokens and Refresh Tokens

Coinbase uses an optional security feature of OAuth2 called refresh tokens.

When you first authenticate, your app will be given an access_token and refresh_token. The access token is used to authenticate all your requests, but will expire in two hours. Once an access token has expired, you will need to use the refresh token to obtain a new access token and refresh token. The refresh token is one time use, so it can only be exchanged once for a new set of access and refresh tokens.

This complicates the integration, but provides an additional layer of security since a compromised access token is automatically revoked after two hours.

If you are using an OAuth2 library that supports refresh tokens, you won't need to worry about this as the library will take care of it for you. Otherwise, you will have to implement your own logic to get a new access token at least every two hours using the refresh token.

Developing Mobile And Desktop Apps

If you're developing an installed application, you may not have a redirect url. In these cases you can set the redirect url to this special value: urn:ietf:wg:oauth:2.0:oob. This tells our servers to render a blank page with the authorization code in the url and title of the page, which can be parsed by your application.

This uses the same pattern that Google follows in their documentation. Here's a great guide with sample code for both iOS and Android.

Simple API Key Access Deprecated

Deprecation notice

This key is a Simple API Key. These type of keys are being deprecated.
For your security, please move to the new API Key + Secret keys.

API Key transition

The only way you can have a Simple API Key right now is if you had enabled API Key access before February 6th, 2014. Since then, we have moved to a more secure form that includes a secret and request signing, called API Key + Secret.

For more information read our blog post on the transition.

Also note that creating new Simple API Keys is not possible anymore. They will be discontinued in August 2014.

Example

Request:

https://coinbase.com/api/v1/account/balance?api_key=YOUR_API_KEY

Response:

{"amount"=>"50.00000000", "currency"=>"BTC"}

The api_key parameter can be included in one of three ways:

  • As a GET parameter in the URL (like above)
  • As a root-level parameter in your JSON requests
  • In the Authorization header of your requests. Example.

Keep in mind that when using your API key in the url, not all API urls can be copied/pasted right into a browser unless they are GET requests like the balance call above.

Security Notes

Storing Credentials Securely

You should take great care to ensure your credentials are stored securely. If someone obtains your api_key or an access_token with the send or all permission, they will be able to send all the bitcoin out of your account.

In particular, you should avoid storing these credentials in your code base (which gets added to version control) or in your database unless you have encrypted them securely. Separating credentials from your code base and database is a good practice.

API key access is turned off by default on all accounts. So if you decide to do an API key integration, you will need to enable it first and take the necessary steps from then on to store it securely. You can always regenerate your API key (or disable it) if you feel it has been compromised.

Validating SSL Certificates

It is also very important that your application validates our SSL certificate when it connects over https. This helps prevent a man in the middle attack. If you are using a client library, this may be turned on by default, but it is worth double checking. If you see a setting to 'verify SSL' you should always ensure it is set to true.

More Security for API Keys

If you need more security with your API Keys, we recommend that you whitelist IP addresses that are permitted to make requests with a particular API Key.

You can do so when either creating a new API Key or editing an existing one.