Add docstrings

Author: vincent-stytch

stytch/consumer/api/idp.py

@@ -32,6 +32,16 @@ def introspect_idp_access_token(
         client_secret: Optional[str] = None,
         token_type_hint: str = "access_token",
     ) -> Optional[AccessTokenJWTClaims]:
+        """Introspects a token JWT from an authorization code response.
+        Access tokens and refresh tokens are JWTs signed with the project's JWKs.
+        Access tokens contain a standard set of claims as well as any custom claims generated from templates.
+
+        Fields:
+          - access_token: The access token (or refresh token) to introspect.
+          - client_id: The ID of the client.
+          - client_secret: The secret of the client.
+          - token_type_hint: A hint on what the token contains. Valid fields are 'access_token' and 'refresh_token'.
+        """
         return self.introspect_idp_access_token_local(
             access_token, client_id
         ) or self.introspect_idp_access_token_network(
@@ -45,6 +55,16 @@ async def introspect_idp_access_token_async(
         client_secret: Optional[str] = None,
         token_type_hint: str = "access_token",
     ) -> Optional[AccessTokenJWTClaims]:
+        """Introspects a token JWT from an authorization code response.
+        Access tokens and refresh tokens are JWTs signed with the project's JWKs.
+        Access tokens contain a standard set of claims as well as any custom claims generated from templates.
+
+        Fields:
+          - access_token: The access token (or refresh token) to introspect.
+          - client_id: The ID of the client.
+          - client_secret: The secret of the client.
+          - token_type_hint: A hint on what the token contains. Valid fields are 'access_token' and 'refresh_token'.
+        """
         local_introspection_response = self.introspect_idp_access_token_local(access_token, client_id)
         if local_introspection_response is not None:
             return local_introspection_response
@@ -59,6 +79,16 @@ def introspect_idp_access_token_network(
         client_secret: Optional[str] = None,
         token_type_hint: str = "access_token",
     ) -> Optional[AccessTokenJWTClaims]:
+        """Introspects a token JWT from an authorization code response.
+        Access tokens and refresh tokens are JWTs signed with the project's JWKs.
+        Access tokens contain a standard set of claims as well as any custom claims generated from templates.
+
+        Fields:
+          - access_token: The access token (or refresh token) to introspect.
+          - client_id: The ID of the client.
+          - client_secret: The secret of the client.
+          - token_type_hint: A hint on what the token contains. Valid fields are 'access_token' and 'refresh_token'.
+        """
         headers: Dict[str, str] = {"Content-Type": "application/x-www-form-urlencoded"}
         data: Dict[str, Any] = {
             "token": access_token,
@@ -95,6 +125,16 @@ async def introspect_idp_access_token_network_async(
         client_secret: Optional[str] = None,
         token_type_hint: str = "access_token",
     ) -> Optional[AccessTokenJWTClaims]:
+        """Introspects a token JWT from an authorization code response.
+        Access tokens and refresh tokens are JWTs signed with the project's JWKs.
+        Access tokens contain a standard set of claims as well as any custom claims generated from templates.
+
+        Fields:
+          - access_token: The access token (or refresh token) to introspect.
+          - client_id: The ID of the client.
+          - client_secret: The secret of the client.
+          - token_type_hint: A hint on what the token contains. Valid fields are 'access_token' and 'refresh_token'.
+        """
         headers: Dict[str, str] = {"Content-Type": "application/x-www-form-urlencoded"}
         data: Dict[str, Any] = {
             "token": access_token,
@@ -129,6 +169,14 @@ def introspect_idp_access_token_local(
         access_token: str,
         client_id: str,
     ) -> Optional[AccessTokenJWTClaims]:
+        """Introspects a token JWT from an authorization code response.
+        Access tokens and refresh tokens are JWTs signed with the project's JWKs.
+        Access tokens contain a standard set of claims as well as any custom claims generated from templates.
+
+        Fields:
+          - access_token: The access token (or refresh token) to introspect.
+          - client_id: The ID of the client.
+        """
         _scope_claim = "scope"
         generic_claims = jwt_helpers.authenticate_jwt_local(
             project_id=self.project_id,

stytch/consumer/models/idp.py

@@ -6,11 +6,16 @@
 
 
 class AccessTokenJWTResponse(ResponseBase):
-    """Response type for `Sessions.introspect_idp_access_token`.
+    """Response type for `IDP.introspect_idp_access_token`.
     Fields:
       - active: Whether or not this token is active.
       - sub: Subject of this JWT.
       - scope: A space-delimited string of scopes this JWT is granted.
+      - aud: Audience of this JWT. Usually the user or member ID, and any custom audience, if present.
+      - exp: Expiration of this access token, in Unix time.
+      - iat: The time this access token was issued.
+      - iss: The issuer of this access token.
+      - nbf: The time before which the JWT must not be accepted for processing.
     """  # noqa
 
     active: bool
@@ -24,11 +29,16 @@ class AccessTokenJWTResponse(ResponseBase):
 
 
 class AccessTokenJWTClaims(pydantic.BaseModel):
-    """Response type for `Sessions.introspect_idp_access_token`.
+    """Response type for `IDP.introspect_idp_access_token`.
     Fields:
       - subject: The subject (either user_id or member_id) that the JWT is intended for.
       - scope: A space-delimited string of scopes this JWT is granted.
       - custom_claims: A dict of custom claims of the JWT.
+      - audience: Audience of this JWT. Usually the user or member ID, and any custom audience, if present.
+      - expires_at: Expiration of this access token, in Unix time.
+      - issued_at: The time this access token was issued.
+      - issuer: The issuer of this access token.
+      - not_before: The time before which the JWT must not be accepted for processing.
     """  # noqa
 
     subject: str