Develop an OAuth APP (GitHub APP) with Web Flow¶
OAuth web flow allows you to authenticate as a user and act on behalf of the user.
Note that if you are developing a GitHub APP, you may opt-in / opt-out of the user-to-server token expiration feature. If you opt-in, the user-to-server token will expire after a certain period of time, and you need to use the refresh token to generate a new token. In this case, you need to do more work to handle the token refresh. See GitHub Docs - Refreshing user access tokens for more information.
Sync Example¶
If you are developing an OAuth APP or a GitHub APP without user-to-server token expiration:
from githubkit.versions.latest.models import PublicUser, PrivateUser
from githubkit import GitHub, OAuthAppAuthStrategy, OAuthTokenAuthStrategy
github = GitHub(OAuthAppAuthStrategy("<client_id>", "<client_secret>"))
# redirect user to github oauth page and get the code from callback
user_github = github.with_auth(github.auth.as_web_user("<code>")) # (1)!
# === or ===
auth: OAuthTokenAuthStrategy = github.auth.as_web_user("<code>").exchange_token(
github
) # (2)!
access_token = auth.token
user_github = github.with_auth(
OAuthTokenAuthStrategy("<client_id>", "<client_secret>", token=access_token)
) # (3)!
# now you can act as the user
resp = user_github.rest.users.get_authenticated()
user: PublicUser | PrivateUser = resp.parsed_data
# you can get the user name and id now
username = user.login
user_id = user.id
- If you just want to use the user token once, simply switch to OAuth Web Auth Strategy.
- exchange the user token manually and store it in a database.
- restore the user token from database
If you are developing a GitHub APP with user-to-server token expiration:
from githubkit.versions.latest.models import PublicUser, PrivateUser
from githubkit import GitHub, OAuthAppAuthStrategy, OAuthTokenAuthStrategy
github = GitHub(OAuthAppAuthStrategy("<client_id>", "<client_secret>"))
# redirect user to github oauth page and get the code from callback
user_github = github.with_auth(github.auth.as_web_user("<code>")) # (1)!
# === or ===
auth: OAuthTokenAuthStrategy = github.auth.as_web_user("<code>").exchange_token(
github
) # (2)!
refresh_token = auth.refresh_token
auth = OAuthTokenAuthStrategy(
"<client_id>", "<client_secret>", refresh_token=refresh_token
) # (3)!
auth.refresh(github) # (4)!
refresh_token = auth.refresh_token
user_github = github.with_auth(auth)
# now you can act as the user
resp = user_github.rest.users.get_authenticated()
user: PublicUser | PrivateUser = resp.parsed_data
# you can get the user name and id now
username = user.login
user_id = user.id
- If you just want to use the user token once, simply switch to OAuth Web Auth Strategy.
- exchange the user token manually and store it in a database.
- restore the user refresh token from database and generate a new token.
- refresh the token manually and store the new one. otherwise, the token will be refreshed automatically when you make a request.
Async Example¶
If you are developing an OAuth APP or a GitHub APP without user-to-server token expiration:
from githubkit.versions.latest.models import PublicUser, PrivateUser
from githubkit import GitHub, OAuthAppAuthStrategy, OAuthTokenAuthStrategy
github = GitHub(OAuthAppAuthStrategy("<client_id>", "<client_secret>"))
# redirect user to github oauth page and get the code from callback
user_github = github.with_auth(github.auth.as_web_user("<code>")) # (1)!
# === or ===
auth: OAuthTokenAuthStrategy = await github.auth.as_web_user(
"<code>"
).async_exchange_token(github) # (2)!
access_token = auth.token
user_github = github.with_auth(
OAuthTokenAuthStrategy("<client_id>", "<client_secret>", token=access_token)
) # (3)!
# now you can act as the user
resp = await user_github.rest.users.async_get_authenticated()
user: PublicUser | PrivateUser = resp.parsed_data
# you can get the user name and id now
username = user.login
user_id = user.id
- If you just want to use the user token once, simply switch to OAuth Web Auth Strategy.
- exchange the user token manually and store it in a database.
- restore the user token from database
If you are developing a GitHub APP with user-to-server token expiration:
from githubkit.versions.latest.models import PublicUser, PrivateUser
from githubkit import GitHub, OAuthAppAuthStrategy, OAuthTokenAuthStrategy
github = GitHub(OAuthAppAuthStrategy("<client_id>", "<client_secret>"))
# redirect user to github oauth page and get the code from callback
user_github = github.with_auth(github.auth.as_web_user("<code>")) # (1)!
# === or ===
auth: OAuthTokenAuthStrategy = await github.auth.as_web_user(
"<code>"
).async_exchange_token(github) # (2)!
refresh_token = auth.refresh_token
auth = OAuthTokenAuthStrategy(
"<client_id>", "<client_secret>", refresh_token=refresh_token
) # (3)!
await auth.async_refresh(github) # (4)!
refresh_token = auth.refresh_token
user_github = github.with_auth(auth)
# now you can act as the user
resp = await user_github.rest.users.async_get_authenticated()
user: PublicUser | PrivateUser = resp.parsed_data
# you can get the user name and id now
username = user.login
user_id = user.id
- If you just want to use the user token once, simply switch to OAuth Web Auth Strategy.
- exchange the user token manually and store it in a database.
- restore the user refresh token from database and generate a new token.
- refresh the token manually and store the new one. otherwise, the token will be refreshed automatically when you make a request.