OAuth 2.0 Token Structure and Certificate Rotation
See the following sections for information about the access, refresh, and id token structure, and the certificate rotation:
Access and Refresh Token Structure
Both the access token and refresh token include three parts: a header, a payload, and a signature.
The token header includes the following parameters:
|
Parameter Name |
Description |
|---|---|
|
kid |
The value of the kid parameter is the ID of the certificate used for signing the token. |
|
typ |
The value of the type parameter is |
|
alg |
The value of the alg parameter is |
The token payload includes the following parameters:
|
Parameter Name |
Description |
|---|---|
|
sub |
The value of the sub parameter is the role and entity of the user, separated by a semicolon. For example, 1111;10. |
|
aud |
The value of the aud parameter is the Application ID of the integration record, and the company, separated by a semicolon. Additionally, the client ID is a part of the aud parameter, separated by a comma. For example, 1A111AA1–AA11–1A11–1111–A1A1111111A1;1111, 661131f7bf0a2f8a4d09c79d3fa961eab66102dca43e07ad47d3a29628ced67b. |
|
scope |
The value of the scope parameter is either |
|
iss |
The value of the iss parameter is |
|
oit |
The value of the oit parameter represents the number of seconds since the first token of the token chain was issued. This is only applicable for public clients. |
|
exp |
The value of the exp parameter represents the number of seconds since January 1, 1970, until the token’s expiration. |
|
iat |
The value of the iat parameter represents when the token was issued. The value of the parameter is in seconds, since January 1, 1970. |
|
jti |
The value of the jti parameter is the token ID, which is unique for every token. |
The token’s dot-separated values are Base64 encoded.
The signature is validated with a public key associated with the kid parameter. To access public keys for your account, use the following URL:
https://<accountID>.suitetalk.api.netsuite.com/services/rest/auth/oauth2/v1/keys
where <accountID> represents your NetSuite account ID.
ID Token Structure
The id token includes three parts: a header, a payload, and a signature.
The token header includes the following parameters:
|
Parameter Name |
Description |
|---|---|
|
kid |
The value of the kid parameter is the ID of the certificate used for signing the token. |
|
typ |
The value of the type parameter is |
|
alg |
The value of the alg parameter is |
The token payload includes the following parameters:
|
Parameter Name |
Description |
|---|---|
|
at_hash |
The value of the at_hash parameter is the signature of the associated access token. |
|
sub |
The value of the sub parameter is the role and entity of the user, separated by a semicolon. For example, 1111;10. |
|
aud |
The value of the aud parameter is the Application ID of the integration record, and the company, separated by a semicolon. Additionally, the client ID is a part of the aud parameter, separated by a comma. For example, 1A111AA1–AA11–1A11–1111–A1A1111111A1;1111, 661131f7bf0a2f8a4d09c79d3fa961eab66102dca43e07ad47d3a29628ced67b. |
|
email_verified |
As of NetSuite 2021.1, the value of the email_verified parameter is always |
|
scope |
The value of the scope parameter is either |
|
iss |
The value of the iss parameter is |
|
exp |
The value of the exp parameter represents the number of seconds until the token’s expiration. |
|
iat |
The value of the iat parameter represents the number of seconds since the token was issued. |
|
nonce |
The value of the nonce parameter is the same as in Step One. |
|
jti |
The value of the jti parameter is the token ID, unique for every token. |
|
|
The value of the email parameter is the user’s email. If the |
The token’s dot-separated values are Base64 encoded.
The signature is validated with a public key, which is associated with the kid parameter. To access public keys for your account, use the following URL:
https://<accountID>.suitetalk.api.netsuite.com/services/rest/auth/oauth2/v1/keys
where <accountID> represents your NetSuite account ID.
Certificate Rotation
As of NetSuite 2021.1, the certificates used to validate access and refresh tokens during the OAuth 2.0 code grant flow are no longer valid indefinitely.
The certificates are valid for 90 days and the system generates new certificates 30 days before the previous certificates expire.
The certificates are company-specific.
Related Topics
- NetSuite as OIDC Provider
- NetSuite as OIDC Provider for Integration Application Developers
- OAuth 2.0 Authorization Code Grant Flow
- Step One GET Request to the Authorization Endpoint
- Step Two POST Request to the Token Endpoint
- Refresh Token POST Request to the Token Endpoint
- Request to the Logout Endpoint
- Troubleshooting NetSuite as OIDC Provider