What is the difference between a Stripe Access Token and API SK key?

Question

The Stripe API reference says this about authentication:

The example they give is this:

require "stripe" 
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

The sk_test_BQokikJOvBiI2HlWgH4olfQ2 secret key is found in the account settings on Stripe's webpage. I understand this is the secret api key for my application to talk with Stripe.

But then I read this documentation on getting started with Stripe Connect:

When using our official API libraries, we recommend that you pass in the 
access_token with every request, instead of setting the API key globally. 
This is because the access_token used in any API request depends on the user 
you're charging on behalf of. 

The example they give is:

# Not recommended: setting global API key state
Stripe.api_key = ACCESS_TOKEN
Stripe::Customer.create(
  :description => "[email protected]"
)

# Recommended: sending API key with every request
Stripe::Customer.create(
  {:description => "[email protected]"},
  ACCESS_TOKEN # user's access token from the Stripe Connect flow
)

Here, the access token is returned to the application after a user has connected to the application through Stripe Connect. The access token can be used to perform actions on behalf of that user, like charging their card.

So, they pass the API key with every request, but why would the user's access token be an api key? I thought from the first documentation that the api key is supposed to be my application's secret api key? Instead, they are setting the user's access token. How will Stripe identify my application then if I'm setting the user's access token and not my own secret key?

Then, I read their example on integrating Stripe Checkout with Sinatra. The code sample they give is:

require 'sinatra'
require 'stripe'

set :publishable_key, ENV['PUBLISHABLE_KEY']
set :secret_key, ENV['SECRET_KEY']

Stripe.api_key = settings.secret_key

....

get '/' do
  erb :index
end

post '/charge' do
  # Amount in cents
  @amount = 500

  customer = Stripe::Customer.create(
    :email => '[email protected]',
    :card  => params[:stripeToken]
  )

  charge = Stripe::Charge.create(
    :amount      => @amount,
    :description => 'Sinatra Charge',
    :currency    => 'usd',
    :customer    => customer.id
  )

  erb :charge
end

So in this instance, they set the API Key to be the application's secret key. They don't pass any Access Token in the request either. So I'm a bit confused why an Access Token would be set as a secret API Key in the previous doc or why I should pass it with each request, when all their example docs don't even do that.

Answer 1

To understand this, you should know first that the Stripe API can be used to build applications that serve two kinds of audiences:

• to accept payments from end-users as a merchant (normal use-case) and
• to provide add-on services to merchants having their own Stripe accounts (eg. one service helps me configure the emails to be sent out on different Stripe events)

Hence, all the API endpoints can be authorized in two ways:

• the API key way which you can directly get from your Account Settings. This identifies your Stripe account
• the access token way through Stripe Connect. This identifies the Stripe account of the connected merchant.

What the Stripe Connect docs is telling you is that suppose you are building an application that serves use-case #2 above, then you must remember to authorize each of your API calls with the right access token and not have a global API key (which, by the way, is fully acceptable for use case #1) as you might be making changes incorrectly to the wrong account(s).

So, if use case #1 is what you want to do, you don't have to worry about Stripe Connect at all.