Documentation for `X-GitHub-SSO` is suspicious

[jsoref]

Code of Conduct

• [X] I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

https://github.com/github/docs/blob/4f40b22909f8192b70b557ee69fb46ceedb43b89/content/rest/authentication/authenticating-to-the-rest-api.md?plain=1#L54

What part(s) of the article would you like to see updated?

If you receive a 403 Forbidden error, you can follow the URL in the X-GitHub-SSO header to authorize your token. The URL expires after one hour. If you requested data that could come from multiple organizations, the API will not return results from the organizations that require SAML SSO. The X-GitHub-SSO header will indicate the ID of the organizations that require SAML SSO authorization of your {% data variables.product.pat_v1 %}. For example: X-GitHub-SSO: partial-results; organizations=21955855,20582480.

The first two sentences of the text imply that X-GitHub-SSO contains a URL. The last line in the paragraph provides an example of an X-GitHub-SSO field that does not contain a URL.

Additional information

It feels like this text should be split into multiple paragraphs, one for "if you aren't authorized" and one for "if you are authorized". But, I don't know, because I don't have access to this.

[nguyenalex836]

@jsoref Thanks for opening this issue! I'll get this triaged for review ✨

[github-actions[bot]]

Thanks for opening an issue! We've triaged this issue for technical review by a subject matter expert :eyes:

[skedwards88]

(Internal note: asked here)

[skedwards88]

Thanks for this issue! We can update the text to say this instead, which I think should clarify your confusion:

If you do not authorize your {% data variables.product.pat_v1 %} for SAML SSO before you try to use it to access an organization that enforces SAML SSO, you may receive a 404 Not Found or a 403 Forbidden error. If you receive a 403 Forbidden error, the X-GitHub-SSO header will include a URL that you can follow to authorize your token. The URL expires after one hour. If you requested data that could come from multiple organizations, instead of returning an error, the API will not return results from the organizations that require SAML SSO and the X-GitHub-SSO header will instead indicate the ID of the organizations that require SAML SSO authorization of your {% data variables.product.pat_v1 %}. For example: X-GitHub-SSO: partial-results; organizations=21955855,20582480.

You or anyone is welcome to open a PR to update this.

[jsoref]

@skedwards88: are you ok w/ splitting it into more than one paragraph? I find these things really hard to read as run-on paragraphs...

[gsosm0760]

Emeğinize sağlık

[skedwards88]

Sure. In that case, I'd probably add a new header above the preceding paragraph to indicate that the following content is all about SAML SSO. So something like:

{% data variables.product.pat_generic_caps_plural %} and SAML SSO

{% ifversion fpt or ghec %}If you use a {% data variables.product.pat_v1 %} to access an organization that enforces SAML single sign-on (SSO) for authentication, you will need to authorize your token after creation.{% ifversion pat-v2 %} {% data variables.product.pat_v2_caps %}s are authorized during token creation, before access to the organization is granted.{% endif %} For more information, see "AUTOTITLE."

If you do not authorize your {% data variables.product.pat_v1 %} for SAML SSO before you try to use it to access a single organization that enforces SAML SSO, you may receive a 404 Not Found or a 403 Forbidden error. If you receive a 403 Forbidden error, the X-GitHub-SSO header will include a URL that you can follow to authorize your token. The URL expires after one hour.

If you do not authorize your {% data variables.product.pat_v1 %} for SAML SSO before you try to use it to access multiple organizations, the API will not return results from the organizations that require SAML SSO and the X-GitHub-SSO header will indicate the ID of the organizations that require SAML SSO authorization of your {% data variables.product.pat_v1 %}. For example: X-GitHub-SSO: partial-results; organizations=21955855,20582480.