view release on metacpan or  search on metacpan

lib/GitHub/Authorization.pm  view on Meta::CPAN

=item *

scopes

An ArrayRef of scopes (described L</Legal Scopes>).

=item *

note

A short note (or reminder) describing what the authorization is for.

=item *

note_url

A link that describes why the authorization has been generated
We throw an exception on error or failure, and return the structure describing
the new authorization token (and the token itself, as described below) on
success.

=item *

client_id (required if client_secret is given)

If requesting an authorization for a specific app, pass its client key here.

=item *

client_secret (required if client_id is given)

If requesting an authorization for a specific app, pass its client secret here.

=back

=head3 On success...

A successful return from get_gh_token() will look something like this:

    {
        app => {
            name => "test! (API)",
            url  => "http://developer.github.com/v3/oauth/#oauth-authorizations-api",
        },
        created_at => "2012-12-24T14:28:17Z",
        id         => xxxxxxx, # an integer > 0
        note       => "test!",
        note_url   => undef,
        scopes     => ["public_repo"],
        token      => "****************************************",
        updated_at => "2012-12-24T14:28:17Z",
        url        => "https://api.github.com/authorizations/xxxxxxx",
    }

The C<token> slot is probably the bit you want.

=head3 On failure/error...

On failure, we confess() our sins:

    Failed: 401/Unauthorized / Bad credentials ...

That is, we L<Carp/confess> with the status code, status message, and the
message returned from GitHub itself.

=head2 legal_scopes

Returns a list of legal scope names.  (See get_gh_token() doc for the list)

=head2 is_legal_scope('scope_name')

Returns true if the scope name given is a legal scope.

=head1 MANAGING AUTHORIZATIONS

All of a user's GitHub authorization tokens can be viewed and revoked on their
L<GitHub Applications|https://github.com/settings/applications> account page.

Users may revoke tokens at any time through GitHub proper.

=head1 SSL VALIDATION

We instruct our user-agent (L<HTTP::Tiny> in this case) to validate the remote
server's certificate, as described in L<HTTP::Tiny/SSL-SUPPORT>.
(Essentially, using L<Mozilla::CA>).

While this satisfies the "let's be cautious" alarms in the author's head,
this may be too paranoid or not paranoid enough for you.  If so, please file
an issue or pull request and we'll work something out.

=head1 LIMITATIONS

This package currently has no capabilities for deleting, altering, or
otherwise doing anything with tokens outside of creating them.

=head1 SEE ALSO

Please see those modules/websites for more information related to this module.

=over 4

=item *

L<The GitHub OAuth API reference|http://developer.github.com/v3/oauth/#create-a-new-authorization>

=item *

L<Net::GitHub>

=item *

L<Pithub>

=back

=head1 SOURCE

The development version is on github at L<http://github.com/RsrchBoy/github-authorization>
and may be cloned from L<git://github.com/RsrchBoy/github-authorization.git>

=head1 BUGS