Need Help? Support

Authorization

OAuth 2

Singly uses standard OAuth 2.0 authorization flow. Singly is entirely behind the scenes, your end users still see your app name in the authorization dialog and you can use all your own API keys. Singly simply handles all the boring stuff (auth token exchange, HMAC signing, etc ) with the external service (Facebook, Twitter, etc).

To start, forward the user to:

https://api.singly.com/oauth/authenticate

With the following required parameters:

Optional parameters:

  • access_token - If specified, links a new profile to the account associated with the provided access_token. Otherwise, a new account is created on the first authentication with each service.

  • scope - For services that support scope, to override the default settings pass in a custom value here to be used during the auth process (format is service-dependent but usually comma delimited)

  • response_type - Specifies the method (code or token) by which your application will receive an access_token once authorization is complete. The default value is code. If you specify code, the response will include a code which can be submitted back to the server to access the OAuth token. Alternatively, token will cause the response to include the OAuth token as a query parameter on the redirect_uri.

  • flag Some services require extra options, right now for twitter if your app's key required DM permission, set flag=dm to use a different auth flow, see this discussion.

  • force_login If you want to ask the service to present a new login dialog during the auth flow, set this to true (currently only twitter and facebook support this)

So the final URL might look like:

https://api.singly.com/oauth/authenticate?client_id=131cb07e5d121ab1fe152&redirect_uri=http%3A%2F%2Fapp.com%2Fcallback&service=twitter

The user will be prompted to authorize Twitter, after which they will be redirected back to:

https://yourapp.com/callback?code=<code>

If there's any error authorizing them (the service doesn't respond, user denied the auth request, etc), they will be redirected back with the error message, the contents of which will vary and are not meant for display:

https://yourapp.com/callback?error=auth+failed

You will then make a POST back to:

https://api.singly.com/oauth/access_token

With the following parameters in the body:

  • client_id Your Singly OAuth 2 client ID
  • client_secret Your Singly OAuth 2 client secret
  • code the code that was passed back in the URL above
  • profile (optional) if set to all it will include a profile object that is the same as /profile, if set to last it will be the same format but only of the service just used. Other /profile parameters of auth=true and full=true can be set here as well to include the tokens of the service and/or the full profile object.

You will receive a JSON object that looks like:

{
   "access_token": "S0meAcc3ssT0k3n",
   "account": "36b62eda6b24f323657c07c7bb764140"
}

The account id is unique to this person and your application and is the parent id for all the profiles that are authenticated to it. Passing the access_token back in to a new authenticate will attach new services to this same account. You can store the account value as the unique key key along with the most recent access_token value to access data for any of the profiles for that person.

The access_token will change every time as it internally contains a timestamp. It's best practice to store the newest one, but old ones don't expire and will continue to work identically. They will always be less than 255 characters in length.

You can then use the access token on all api requests like so:

https://api.singly.com/profiles?access_token=S0meAcc3ssT0k3n

Configuration

For detailed instructions on registering your application with services to use your own keys through Singly, read the Application Configuration docs.

Examples

These skeleton repositories all illustrate basic auth flow and API usage.

Browser-based Client Apps

If your app doesn't have a server and is entirely browser based, you can get the token by using the response_type parameter value token, as specified above.

A successful auth will be redirected to the redirect_url appended with #access_token=**** which can be read from the DOM in that page, you can test this and see an example final url by visiting the following URL, which will redirect back to singly.com with the token appended:

    https://api.singly.com/oauth/authenticate?client_id=singly-dev-registration&service=facebook&redirect_uri=https%3A%2F%2Fsingly.com%2F&scope=email&response_type=token

Custom Account Management

If your app is already managing the auth for your users, you can still create representative accounts to do the syncing and data work for any service. Make sure you have your app's keys for the given service saved at https://singly.com/ and that they match the same service keys used to generate the tokens before using this so that the given tokens can be authenticated via the service.

To do this, use the endpoint

https://api.singly.com/auth/:service/apply

With the following parameters:

  • client_id Your Singly OAuth 2 client ID
  • client_secret Your Singly OAuth 2 client secret
  • token The access token value for the service
  • token_secret Only for OAuth 1 based services (like twitter and tumblr) is this required
  • account If an existing account is known and this auth should connect the new profile into an existing account, it can be specified here, the fallback will always create a new account

So the final URL might look like this to create a new Singly account for the facebook profile already authorized with the given token:

https://api.singly.com/auth/facebook/apply?token=XXXXX&client_id=8597909a2db58cf74e27e40a9ee2b5e1&client_secret=df43c02b87125e7aab3bb543153438aa

Merging Accounts

Sometimes an app has two accounts that need to be merged (user began a new auth flow, but had an existing account), there's a simple endpoint that will provide this functionality:

GET /auth/merge?source=TOKENA&dest=TOKENB

Any profiles from the account for TOKENA will be merged into the account for TOKENB, and then the source account will be deleted and TOKENA will be invalid. It will return the same result as /profiles showing everything then combined for the dest account.