Module: Octokit::Client::Authorizations

Included in:
Octokit::Client
Defined in:
lib/octokit/client/authorizations.rb

Overview

Methods for the Authorizations API

See Also:

Instance Method Summary collapse

Instance Method Details

#authorization(number, options = {}) ⇒ Sawyer::Resource

Get a single authorization for the authenticated user.

You can only access your own tokens, and only through Basic Authentication.

Examples:

Show authorization for user ctshryock’s Travis auth

client = Octokit::Client.new(:login => 'ctshryock', :password => 'secret')
client.authorization(999999)

Returns:

  • (Sawyer::Resource) —

    A single authorization for the authenticated user

See Also:



34
35
36
 
# File 'lib/octokit/client/authorizations.rb', line 34

def authorization(number, options = {})
  get "authorizations/#{number}", options
end

#authorizations(options = {}) ⇒ Array<Sawyer::Resource>

List the authenticated user’s authorizations

API for users to manage their own tokens. You can only access your own tokens, and only through Basic Authentication.

Examples:

List authorizations for user ctshryock

client = Octokit::Client.new(:login => 'ctshryock', :password => 'secret')
client.authorizations

Returns:

  • (Array<Sawyer::Resource>) —

    A list of authorizations for the authenticated user

See Also:



20
21
22
 
# File 'lib/octokit/client/authorizations.rb', line 20

def authorizations(options = {})
  paginate 'authorizations', options
end

#authorize_url(app_id = client_id, options = {}) ⇒ String

Get the URL to authorize a user for an application via the web flow

Examples:

@client.authorize_url('xxxx')

Parameters:

  • app_id (String) (defaults to: client_id) —

    Client Id we received when our application was registered with GitHub.

  • options (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (options):

  • :redirect_uri (String) —

    The url to redirect to after authorizing.

  • :scope (String) —

    The scopes to request from the user.

  • :state (String) —

    A random string to protect against CSRF.

Returns:

  • (String) —

    The url to redirect the user to authorize.

See Also:



228
229
230
231
232
233
234
235
236
237
238
239
240
241
 
# File 'lib/octokit/client/authorizations.rb', line 228

def authorize_url(app_id = client_id, options = {})
  if app_id.to_s.empty?
    raise Octokit::ApplicationCredentialsRequired.new "client_id required"
  end
  authorize_url = options.delete(:endpoint) || Octokit.web_endpoint
  authorize_url << "login/oauth/authorize?client_id=#{app_id}"

  require 'cgi'
  options.each do |key, value|
    authorize_url << "&#{key}=#{CGI.escape value}"
  end

  authorize_url
end

#check_application_authorization(token, options = {}) ⇒ Sawyer::Resource

Check if a token is valid.

Applications can check if a token is valid without rate limits.

Examples:

client = Octokit::Client.new(:client_id => 'abcdefg12345', :client_secret => 'secret')
client.check_application_authorization('deadbeef1234567890deadbeef987654321')

Parameters:

  • token (String) —

    40 character GitHub OAuth access token

Returns:

  • (Sawyer::Resource) —

    A single authorization for the authenticated user

See Also:



149
150
151
152
153
154
155
156
157
 
# File 'lib/octokit/client/authorizations.rb', line 149

def check_application_authorization(token, options = {})
  opts = options.dup
  key    = opts.delete(:client_id)     || client_id
  secret = opts.delete(:client_secret) || client_secret

  as_app(key, secret) do |app_client|
    app_client.get "applications/#{client_id}/tokens/#{token}", opts
  end
end

#create_authorization(options = {}) ⇒ Sawyer::Resource

Create an authorization for the authenticated user.

You can create your own tokens, and only through Basic Authentication.

Examples:

Create a new authorization for user ctshryock’s project Zoidberg

client = Octokit::Client.new(:login => 'ctshryock', :password => 'secret')
client.create_authorization({:scopes => ["public_repo", "gist"], :note => "Why not Zoidberg?", :note_url=> "https://en.wikipedia.org/wiki/Zoidberg"})

Create a new OR return an existing authorization to be used by a specific client for user ctshryock’s project Zoidberg

client = Octokit::Client.new(:login => 'ctshryock', :password => 'secret')
client.create_authorization({:idempotent => true, :client_id => 'xxxx', :client_secret => 'yyyy', :scopes => ["user"]})

Parameters:

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :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.

  • :idempotent (Boolean) —

    If true, will return an existing authorization if one has already been created.

  • :client_id (String) —

    Client Id we received when our application was registered with GitHub.

  • :client_secret (String) —

    Client Secret we received when our application was registered with GitHub.

Returns:

  • (Sawyer::Resource) —

    A single authorization for the authenticated user

See Also:



61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
 
# File 'lib/octokit/client/authorizations.rb', line 61

def create_authorization(options = {})
  # Techincally we can omit scopes as GitHub has a default, however the
  # API will reject us if we send a POST request with an empty body.

  if options.delete :idempotent
    client_id, client_secret = fetch_client_id_and_secret(options)
    raise ArgumentError.new("Client ID and Secret required for idempotent authorizations") unless client_id && client_secret

    if fingerprint = options.delete(:fingerprint)
      put "authorizations/clients/#{client_id}/#{fingerprint}", options.merge(:client_secret => client_secret)
    else
      put "authorizations/clients/#{client_id}", options.merge(:client_secret => client_secret)
    end

  else
    post 'authorizations', options
  end
end

#delete_authorization(number, options = {}) ⇒ Boolean

Delete an authorization for the authenticated user.

You can delete your own tokens, and only through Basic Authentication.

Examples:

Delete an authorization

client = Octokit::Client.new(:login => 'ctshryock', :password => 'secret')
client.delete_authorization(999999)

Parameters:

  • number (Number) —

    An existing Authorization ID

Returns:

  • (Boolean) —

    Success

See Also:



114
115
116
 
# File 'lib/octokit/client/authorizations.rb', line 114

def delete_authorization(number, options = {})
  boolean_from_response :delete, "authorizations/#{number}", options
end

#reset_application_authorization(token, options = {}) ⇒ Sawyer::Resource

Reset a token

Applications can reset a token without requiring a user to re-authorize.

Examples:

client = Octokit::Client.new(:client_id => 'abcdefg12345', :client_secret => 'secret')
client.reset_application_authorization('deadbeef1234567890deadbeef987654321')

Parameters:

  • token (String) —

    40 character GitHub OAuth access token

Returns:

  • (Sawyer::Resource) —

    A single authorization for the authenticated user

See Also:



170
171
172
173
174
175
176
177
178
 
# File 'lib/octokit/client/authorizations.rb', line 170

def reset_application_authorization(token, options = {})
  opts = options.dup
  key    = opts.delete(:client_id)     || client_id
  secret = opts.delete(:client_secret) || client_secret

  as_app(key, secret) do |app_client|
    app_client.post "applications/#{client_id}/tokens/#{token}", opts
  end
end

#revoke_all_application_authorizations(options = {}) ⇒ Boolean

Deprecated.

As of January 25th, 2016: developer.github.com/changes/2014-04-08-reset-api-tokens/

Revoke all tokens for an app

Applications can revoke all of their tokens in a single request

Returns:

  • (Boolean) —

    false



212
213
214
215
 
# File 'lib/octokit/client/authorizations.rb', line 212

def revoke_all_application_authorizations(options = {})
  octokit_warn("Deprecated: If you need to revoke all tokens for your application, you can do so via the settings page for your application.")
  false
end

#revoke_application_authorization(token, options = {}) ⇒ Boolean Also known as: delete_application_authorization

Revoke a token

Applications can revoke (delete) a token

Examples:

client = Octokit::Client.new(:client_id => 'abcdefg12345', :client_secret => 'secret')
client.revoke_application_authorization('deadbeef1234567890deadbeef987654321')

Parameters:

  • token (String) —

    40 character GitHub OAuth access token

Returns:

  • (Boolean) —

    Result

See Also:



191
192
193
194
195
196
197
198
199
200
201
202
203
 
# File 'lib/octokit/client/authorizations.rb', line 191

def revoke_application_authorization(token, options = {})
  opts = options.dup
  key    = opts.delete(:client_id)     || client_id
  secret = opts.delete(:client_secret) || client_secret

  as_app(key, secret) do |app_client|
    app_client.delete "applications/#{client_id}/tokens/#{token}", opts

    app_client.last_response.status == 204
  end
rescue Octokit::NotFound
  false
end

#scopes(token = @access_token, options = {}) ⇒ Array<String>

Check scopes for a token

Parameters:

  • token (String) (defaults to: @access_token) —

    GitHub OAuth token

  • options (Hash) (defaults to: {}) —

    Header params for request

Returns:

  • (Array<String>) —

    OAuth scopes

Raises:

  • (ArgumentError)

See Also:



124
125
126
127
128
129
130
131
132
133
134
135
136
 
# File 'lib/octokit/client/authorizations.rb', line 124

def scopes(token = @access_token, options = {})
  raise ArgumentError.new("Access token required") if token.nil?

  auth = { "Authorization" => "token #{token}" }
  headers = (options.delete(:headers) || {}).merge(auth)

  agent.call(:get, "user", :headers => headers).
    headers['X-OAuth-Scopes'].
    to_s.
    split(',').
    map(&:strip).
    sort
end

#update_authorization(number, options = {}) ⇒ Sawyer::Resource

Update an authorization for the authenticated user.

You can update your own tokens, but only through Basic Authentication.

Examples:

Update the authorization for user ctshryock’s project Zoidberg

client = Octokit::Client.new(:login => 'ctshryock', :password => 'secret')
client.update_authorization(999999, {:add_scopes => ["gist", "repo"], :note => "Why not Zoidberg possibly?"})

Parameters:

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :scopes (Array) —

    Replace 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.

Returns:

  • (Sawyer::Resource) —

    A single (updated) authorization for the authenticated user

See Also:



98
99
100
 
# File 'lib/octokit/client/authorizations.rb', line 98

def update_authorization(number, options = {})
  patch "authorizations/#{number}", options
end