en-US/about_RedditOAuthToken.help.txt

TOPIC
    about_redditoauthtoken
 
SHORT DESCRIPTION
    Describes the RedditOAuthToken Class
 
LONG DESCRIPTION
    The `RedditOAuthToken` Class represents the OAuth Access Token used for
    authentication to the Reddit API. `RedditOAuthToken` objects are required by
    the majority of functions in this module. `Invoke-RedditRequest` uses the
    Access Token in `RedditOAuthToken` objects as a `bearer` Authorization
    header when making requests to Reddit. This way Reddit knows what level of
    access the application has in the API as well as under which user context
    the application is acting. Access Tokens are considering temporary secrets
    and are valid for 60 minutes. Some Access Tokens are also issued with
    Refresh Tokens. Refresh Tokens are permanent secrets and are valid until the
    user or application revokes them. `RedditOAuthToken` objects house the
    Access Token and Refresh Token as a secure strings in a `PSCredential` objects.
    `RedditOAuthToken` objects are returned from the `Request-RedditOAuthToken`
    function. They can be "renewed" using the `Update-RedditOAuthToken`
    function. `RedditOAuthToken` objects can be imported and exported to XML
    files using `Import-RedditOAuthToken` and `Export-RedditOAuthToken`. Doing
    so provides a secure way to store the Access Token, Refresh Token, Client
    Secret, and Reddit user password so that it can later be imported by other
    scripts or in a later console session. This provides the means for
    automation of authenticated access to the Reddit API.
    The same `RedditOAuthToken` should not be used in parallel PowerShell
    sessions. It is important that the `RedditOAuthToken` only be used within
    the same session state or else the token may be updated in another session
    and thus invalidate the `RedditOAuthToken` in the current session causing
    Access Denied errors. Concurrency where the same session is available should
    be fine, but you will still be bound by Reddit's Rate Limiting of `60` API
    calls per minute. It is recommended that if you need concurrency, you
    request multiple Tokens on behalf of multiple users. Otherwise, you should
    obey the rules and guidelines for accessing the Reddit API and code responsibly.
    The functions in this module will automatically enforce rate limiting when
    the the limits for the current Access Token have been reached. this will
    result in the functions sleeping until the rate limit has been lifted. While
    it is possible to circumvent these measures, doing so may result in your
    application or Reddit account being banned.
    The `RedditOAuthToken` class is imported automatically when you import the
    PSRAW module.
 
CONSTRUCTORS
RedditOAuthToken()
    Creates an empty `RedditOAuthToken` object.
 
    [RedditOAuthToken]::new()
 
RedditOAuthToken(RedditOAuthGrantType GrantType, RedditApplication Application, Object Response)
    Creates `RedditOAuthToken` object from the provided `RedditOAuthGrantType`,
    `RedditApplication`, and either a `system.uri` or a
    `Microsoft.PowerShell.Commands.WebResponseObject` shaped object. Depending
    on the grant flow used, the Access Token will be provided in a JSON response
    or in the fragment part of a URI. This constructor builds the
    `RedditOAuthToken` from the data provided in those responses.
 
    [RedditOAuthToken]::new(
        [RedditOAuthGrantType]$GrantType,
        [RedditApplication]$Application,
        [Object]$Response
    )
 
PROPERTIES
Application
    The `RedditApplication` representing the application for which this Access
    Token is valid.
 
    Name: Application
    Type: RedditApplication
    Hidden: False
    Static: False
 
AuthBaseURL
    This static property is defines the Reddit URL where Access Tokens are
    requested.
 
    Name: AuthBaseURL
    Type: String
    Hidden: False
    Static: True
 
DeviceId
    Certain grant flows require a Device ID be send to identify the device that
    is connecting. If a Device ID is provided it will be visible here. Most
    grant flows do not require a device ID and for those grant type this will be
    empty.
 
    Name: DeviceId
    Type: String
    Hidden: False
    Static: False
 
ExpireDate
    A `DateTime` representing the time the Access Token will expire. If the
    Access Token is expired, the functions in this module will attempt to
    automatically renew the token upon the next API call.
 
    Name: ExpireDate
    Type: DateTime
    Hidden: False
    Static: False
 
ExportPath
    This is the path the `RedditOAuthToken` was last imported from or where you
    wish to export it to. It is provided for interaction with
    `Import-RedditOAuthToken` and `Export-RedditOAuthToken`. This should be the
    literal path of the file.
 
    Name: ExportPath
    Type: String
    Hidden: False
    Static: False
 
GrantType
    `RedditOAuthGrantType` representing the grant flow method used to request
    this Access Token. This will be used to determine the update method.
 
    Name: GrantType
    Type: RedditOAuthGrantType
    Hidden: False
    Static: False
 
GUID
    A `Guid` used to help identify the Access Token. This is provided for
    convenience and is not sent to or required by the API. In situations where
    multiple Access Tokens may be in use, this GUID can be used to distinguish
    between them. This GUID will not change when a Token is updated, even for
    methods which require a fresh grant flow. The purpose is to identify a
    specific initial grant for the Access Token.
 
    Name: GUID
    Type: Guid
    Hidden: False
    Static: False
 
IssueDate
    The date this current Access Token was issued. When an Access Token is
    updated this will be updated to reflect the date that the new token was
    issued.
 
    Name: IssueDate
    Type: DateTime
    Hidden: False
    Static: False
 
LastApiCall
    This is a `DateTime` representing the last time this Access Token was used
    to call the API. This will be updated automatically every time a request is
    made to the reddit API.
 
    Name: LastApiCall
    Type: DateTime
    Hidden: False
    Static: False
 
Notes
    This `String` property is provided for convenience to module users. this can
    be used to store session information, a description, a ticket ID, or
    whatever information the module user may deem valuable to associate with the
    Access Token.
 
    Name: Notes
    Type: String
    Hidden: False
    Static: False
 
RateLimitRemaining
    This is the number of API requests remaining before this Access Token will
    be rate limited. Reddit allows for `60` API calls per minute. If this
    reaches `0`, then the Access Token is rate limited and functions will sleep
    until the Rate Limit period is reset.
 
    Name: RateLimitRemaining
    Type: Int32
    Hidden: False
    Static: False
 
RateLimitRest
    This is the amount of time in seconds from the time in `LastApiCall` until
    the Rate Limit period is reset. If `RateLimitRemaining` is `0`, this Access
    Token is rate limited until `LastApiCall` plus `RateLimitRest` and the
    functions in this module will sleep until that time.
 
    Name: RateLimitRest
    Type: Int32
    Hidden: False
    Static: False
 
RateLimitUsed
    This is the number of API calls that have been made since the that Rate
    Limit reset period. This will be `0` when the rate limit period has reset
    and `60` if the Access Token has been Rate Limited.
 
    Name: RateLimitUsed
    Type: Int32
    Hidden: False
    Static: False
 
RefreshCredential
    A `PSCredential` object to house the OAuth Refresh Token.
 
    Name: RefreshCredential
    Type: System.Management.Automation.PSCredential
    Hidden: True
    Static: False
 
Scope
    An array of `RedditOAuthScope` objects representing the OAuth scopes for
    which this Access Token is valid.
 
    Name: Scope
    Type: RedditOAuthScope[]
    Hidden: False
    Static: False
 
Session
    Used to track the web session for `Invoke-GraphRequest` when calls are made
    to Reddit's API. This property will not be imported from
    `Import-RedditOAuthToken` and instead a new
    `Microsoft.PowerShell.Commands.WebRequestSession` will be created. This is
    primarily used to house Reddit's tracking cookies which provide a persistent
    CDN experience.
 
    Name: Session
    Type: Microsoft.PowerShell.Commands.WebRequestSession
    Hidden: True
    Static: False
 
TokenCredential
    A `PSCredential` object to house the OAuth Access Token.
 
    Name: TokenCredential
    Type: System.Management.Automation.PSCredential
    Hidden: True
    Static: False
 
TokenType
    This is the token type returned by Reddit. It should always be `bearer`.
 
    Name: TokenType
    Type: String
    Hidden: False
    Static: False
 
METHODS
GetAccessToken()
    Retrieves the plain-text OAuth Access Token from the `TokenCredential`
    property.
 
    Name: GetAccessToken
    Return Type: String
    Hidden: False
    Static: False
    Definition: String GetAccessToken()
 
GetRateLimitReset()
    Retrieves the time that the Rate Limit period will be be reset.
    (`LastApiCall` plus `RateLimitRest`)
 
    Name: GetRateLimitReset
    Return Type: DateTime
    Hidden: False
    Static: False
    Definition: DateTime GetRateLimitReset()
 
GetRefreshToken()
    Retrieves the plain-text OAuth Refresh Token from the `RefreshCredential`
    property.
 
    Name: GetRefreshToken
    Return Type: String
    Hidden: False
    Static: False
    Definition: String GetRefreshToken()
 
IsExpired()
    Returns `$True` if the token is expired Returns `$False` if the token is not
    expired.
 
    Name: IsExpired
    Return Type: Boolean
    Hidden: False
    Static: False
    Definition: Boolean IsExpired()
 
IsRateLimited()
    Returns `$True` if the access token is Rate Limited Returns `$False` if the
    access token is not Rate Limited
 
    Name: IsRateLimited
    Return Type: Boolean
    Hidden: False
    Static: False
    Definition: Boolean IsRateLimited()
 
Refresh(Object Response)
    Refreshes the `RedditOAuthToken` properties when a token refresh has been
    performed. The response will be either a `system.uri` or a
    `Microsoft.PowerShell.Commands.WebResponseObject` shaped object. Depending
    on the grant flow used, the refreshed Access Token will be provided in a
    JSON response or in the fragment part of a URI.
 
    Name: Refresh
    Return Type: Void
    Hidden: False
    Static: False
    Definition: Void Refresh(Object Response)
 
Reserialize(Object Object)
    Used to reserialize a deserialized `RedditOAuthToken` object. This is called
    by `Import-RedditOAuthToken` after the object has been imported from XML.
 
    Name: Reserialize
    Return Type: RedditOAuthToken
    Hidden: False
    Static: True
    Definition: static RedditOAuthToken Reserialize(Object Object)
 
ToString()
    Returns a string representation of the `RedditOAuthToken` object.
 
    Name: ToString
    Return Type: String
    Hidden: False
    Static: False
    Definition: String ToString()
 
UpdateRateLimit(Object Response)
    Updates the `RateLimitReset`, `RateLimitUsed`, `RateLimitRemaining`, and
    `LastApiCall` properties. This is called after every successful call to the
    Reddit API by `Invoke-RedditRequest`.
 
    Name: UpdateRateLimit
    Return Type: Void
    Hidden: False
    Static: False
    Definition: Void UpdateRateLimit(Object Response)
 
EXAMPLES
Create New Instance With Constructor
    Import-Module PSRAW
    $Application = Import-RedditApplication -Path 'c:\MyApp.xml'
     $Params = @{
        Uri = [RedditOAuthToken]::AuthBaseURL
        Body = @{
            grant_type = 'https://oauth.reddit.com/grants/installed_client'
            device_id = [guid]::NewGuid().ToString()
        }
        UserAgent = $Application.UserAgent
        Headers = @{
            Authorization = 'Basic {0}' -f (
                [System.Convert]::ToBase64String(
                    [System.Text.Encoding]::ASCII.GetBytes(
                        ('{0}:{1}' -f $Application.ClientCredential.UserName,
                        $Application.ClientCredential.GetNetworkCredential().Password)
                    )
                )
            )
        }
        Method = 'POST'
        UseBasicParsing = $true
    }
    $Result = Invoke-WebRequest @Params
    $Token = [RedditOAuthToken]::New('Installed', $Application, $Result)
 
    This example shows how to manually request an OAuth Access Token from Reddit
    using the `installed_client` grant method and use the result to create a
    `RedditOAuthToken` object.
 
Sleep Until Rate Limit Period Reset.
    While ($Token.IsRateLimited()){
        Start-Sleep -Seconds 1
    }
 
    This example demonstrates how to sleep until the the Rate Limit period has
    been reset.
 
SEE ALSO
    about_RedditApplication
    about_RedditOAuthGrantType
    about_RedditOAuthScope
    Export-RedditOAuthToken
    Import-RedditOAuthToken
    Invoke-RedditRequest
    Request-RedditOAuthToken
    Update-RedditOAuthToken
    https://github.com/reddit/reddit/wiki/OAuth2
    https://psraw.readthedocs.io/