• Spaces API

    OAuth 2.0

OAuth 2.0

Spaces API works with OAuth 2.0 access tokens. This is the way to do any API requests. This page will guide you through the process of setting up OAuth 2, but it requires that you already have your Spaces application.

If you don't have your Spaces application just yet, go ahead and create it now.


How does it work?

Stripe has an excellent documentation that is very similar to Spaces. Check it out here.

Setting up the Oauth flow

You'll need the following endpoints:

  • authorize_url: https://gospaces.com/oauth/authorize
  • access_token_url: https://gospaces.com/oauth/token

In the settings page of your Spaces application you'll find the client_id and client_secret parameters. It's also here that you'll set the redirect_uri. This is where the user will be redirected after being authorized (with an authorization_token parameter).

Connecting users

You have to direct the users who needs authorization to the following URL.

https://gospaces.com/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&response_type=code&scope=read_write&state=1234

The state parameter will just pass through. It can be used for e.g. CSRF protection, or identifying users.

We'll prompt the user to allow the authorization. If allowed, we'll redirect the user back to your redirect_uri.

HTTP/1.1 302 Found Location: REDIRECT_URI?scope=read_write&state=1234&code=AUTHORIZATION_CODE

If the authorization was denied, we'll redirect the user with an error code.

HTTP/1.1 302 Found Location: REDIRECT_URI?error=access_denied&error_description=The%20resource%20owner%20or%20authorization%20server%20denied%20the%20request.

Generate access token

With the code parameter you can generate an access token.

curl -X POST https://gospaces.com/oauth/token \ -d client_id=CLIENT_ID \ -d client_secret=CLIENT_SECRET \ -d code=AUTHORIZATION_CODE \ -d redirect_uri=REDIRECT_URI \ -d grant_type=authorization_code

You'll receive a JSON response containing the access_token or error.

{ "token_type": "bearer", "scope": "read_write", "spaces_user_id": USER_ID, "refresh_token": REFRESH_TOKEN, "access_token": ACCESS_TOKEN }

Now you can use the access_token as the API key.

curl https://gospaces.com/api/v1/customers \ -u ACCESS_TOKEN: \

The refresh_token can be used to roll the access_token. Access tokens don't expire, so it's important to record the refresh token for later use.

Webhooks

You can set a webhook URL for your Spaces application. All webhooks send through to application webhook URL will contain a spaces_user_id field in the root level so you can easily connect events to specific users.

{ "object": "event", "created": 1410196574, "type": "customer.created", "spaces_user_id": USER_ID, "data": { "object": { ... } } }