How to access swagger documents for a service

Authentication and Authorization of our endpoints

Most of the endpoints are protected by authentication and authorization.

Authentication

We use WebAccess to authenticate a user. If you try using a service that requires
authentication and you have not authenticated, you will likely receive a 401 error code as a
response. The example below will show you how to authenticate into the service.
Please note there may be a time when you have authenticated, but your session has timed out.
If the page is still up in your browser, but the session has timed out, you will receive a 401
response code if you try running the service.

Refresh the page and reauthenticate before you try using the endpoint.

Authorization

Once you have been authenticated, you will still need to be authorized to use the service. If
you are authenticated and try to run an endpoint, the endpoint will return a 403 error code if
you do not have permission to use the service. In order to be authorized, you will need to
request access from our group to use the service.

Click here to learn more about OAuth.

Click here to watch a video on OAuth.

Please fill out the form on each page by clicking the “Request Authorization” button to request access when needed.

An example of how to call a Swagger Endpoint that does not need Authentication

The common service is one of the few services that have endpoints that do not require authentication. Here are instructions on how to call an endpoint that does not require authentication.

1. Go to the Common Service Page. The URL for the Common Service is
   https://docs.developer.psu.edu/common-services/
2. Go toward the bottom of the page under the heading REST Endpoints for Acceptance
   Environment
3. Expand the campuses section. Two endpoints will be displayed to get a campus or
   campuses
4. Expand the endpoint GET /campuses
5. Click the ‘Try it out!’ button.
6. If the call is successful, it will load the following information:
7. Curl – This is the curl command you can use if you wanted to call the endpoint
   through Curl
8. Request URL – This is the endpoint URL that was called to get the results
9. Response Body – This is the result of the call to the endpoint. Normally, the
   results are in the JSON format.

An example of how to call a Swagger Endpoint that does need Authentication

Calling an endpoint that requires authentication is similar to calling an endpoint that does not
require authentication. There is only one extra step.

For example, let’s call an endpoint in the Email Service that requires authentication.

1. Go to the Common Service Page. The URL for the Common Service is https://docs.developer.psu.edu/email-service/
2. Go toward the bottom of the page under the heading REST Endpoints for Acceptance
   Environment
3. Expand the template section. The first endpoint is to get a template (GET /templates).
   Click on that row to expand it.
4. There will be a button set to off on the right side with an exclamation point. This is
   informing you that you have not been authorized to use this endpoint. Click on the OFF
   slider
5. This will bring up a dialog for you to authenticate. Click the Full Access checkbox and
   then press the Authorize button.
6. If you have authenticated correctly, you will see the button now says on and the red
   the exclamation point is gone.
7. Click the ‘Try it out!’ button. As long as you are also authorized to use the service, the
   call should be successful.

If the call is successful, it will load the following information:

• Curl – This is the curl command you can use if you wanted to call the endpoint through Curl
• Request URL – This is the endpoint URL that was called to get the results
• Response Body – This is the result of the call to the endpoint. Normally, the results are in the JSON format.