Overview

The External Accounts API provides integration with the university’s external account (social) identity provider. An external account represents the connection between the internal guest identifier and the provider identity. Registrations with the provider are started by creating a new External Account.

Requesting Access

To gain access to the External Accounts REST API please send a request to the Identity Management Systems (IMS) team at imsinfo@iu.edu. The Rest API uses the User Authentication and Authorization Service (UAA) to authenticate with EAA_SPONSOR role, so new applications will need to include in their request the generation of an OAuth2 client id and secret. To learn more about using OAuth2 authorization with your applications, please see the UAA documentation.

Existing Guest Accounts

External Accounts replace guest accounts at the university. Existing guest accounts will be copied into this system and retain their existing identification number, name and email data. Users will be required to re-enroll their account using their guest account username (email address) in order to tie it with the university’s external account (social) provider.

HTTP Verbs

This API tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs.

Verb Usage

GET

Retrieve a resource

POST

Create a new resource

PUT

Update an entire existing resource

PATCH

Update an existing resource, including partial updates

DELETE

Delete an existing resource

HTTP Status Codes

The API tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP status codes.

Status code Usage

200 OK

The request completed successfully

201 Created

A new resource has been created successfully. The resource’s URI is available from the response’s Location header

204 No Content

The request was successful, but no content was returned.

400 Bad Request

The request was malformed. The response body will include an error providing further information

401 Unauthorized

The request requires user authentication.

403 Forbidden

Authentication credentials were provided in the request, but the server considers them insufficient to grant access.

404 Not Found

The requested resource does not exist.

500 Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request. Please send an email to imsinfo@iu.edu if you require further assistance.

External Accounts

The External Account resource is used to create and retrieve external accounts.

Retrieve an External Account with an email address

A `GET` request will retrieve an External Account with the provided email address

Example Curl request

$ curl 'http://localhost:8080/accounts/external/search?internetAddress=111111111111%40google.com' -i -X GET

Request Parameters

Parameter Description

internetAddress

The email address associated with the external account

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 491

{
  "externalAccountId" : 9000000000,
  "firstName" : "Willow",
  "lastName" : "Straker",
  "registrationEmail" : "111111111111@google.com",
  "created" : "2024-12-11T15:12:46.675+00:00",
  "linkedAccounts" : [ {
    "linkedAccountId" : "1b09a4e3-0bc5-4feb-814b-aeff19c97b89",
    "accountType" : "EMAIL",
    "accountStatus" : "NEW",
    "internetAddress" : "111111111111@google.com",
    "expirationDate" : "2024-12-12T10:12:46.678805",
    "created" : "2024-12-11T10:12:46.677743"
  } ]
}

Response Structure

Path Type Description

externalAccountId

Number

The unique identifier for the external account

firstName

String

The first name of the registrant

lastName

String

The last name of the registrant

registrationEmail

String

The originating invitation email address of the registrant (If different, the registrant’s email address associated with the social provider will not affect this address)

linkedAccounts

Array

A collection of accounts linked to the external account

linkedAccounts.[0].linkedAccountId

String

The unique identifier for the linked account record

linkedAccounts.[0].accountStatus

String

The status of the account

linkedAccounts.[0].accountType

String

The type of linked account

linkedAccounts.[0].internetAddress

String

The email address for the linked account

linkedAccounts.[0].expirationDate

String

The date time the account will expire if not verified within the allotted time

linkedAccounts.[0].created

String

The date time the linked account was created

created

String

Date the external account was created

Send external account invitation request for Sponsor

Example Curl request

Request Fields

Path Type Description

firstName

String

The first name of the registrant

lastName

String

The last name of the registrant

email

String

The email address of the registrant

serviceName

String

The unique name for the sponsor

Example response

Response Structure

Path Type Description

externalAccountId

String

The unique identifier for the external account

accountStatus

String

The status of the account

firstName

String

The first name of the registrant

lastName

String

The last name of the registrant

email

String

The originating invitation email address of the registrant (If different the registrant’s email address associated with the social provider will not affect this address)

Registration Statuses

This table shows all the registration status values

Registration Status Description

INVITED

The registration process has started with an email generated to the registrant

EXPIRED

The external account has not been validated within the allotted time, and has been expired

VALID

The registration is complete with the provider